Webhooks

Webhooks are a way to receive real-time notifications from the API when a specific event occurs. For example, you can receive an event when a memory is created, updated, or deleted.

To start receiving webhook events, create and register a webhook through the dashboard.

Event types

See Events for a list of all available event types.

Security

A cryptographically secure secret should be generated and persisted on your own server. When you create a webhook in the dashboard, the secret must be provided.

We will use the secret to generate a signature on each webhook request, provided in the x-fency-signature header. See verifying the payload signature for instructions on using the secret to verify that the request originated from Fency.

Verifying the payload signature

Requests to your endpoint will bear an x-fency-signature header verifying that the request has come from us.

The signature is the HMAC hex digest of the payload, where the algorithm is sha256, the key is your own secret, and the payload is the raw UTF-8 request body received from us. The signature is then prefixed with sha256=.

A delivery of {"payload":"example"} signed with example-secret would have an x-fency-signature of sha256=c395de9ac90297578092d5d0394dc8def76ab5561ec1717dadb6aece0f40bd04.

const secret = "example-secret";
const payload = req.body; // {"payload":"example"}

// Read signature from request HTTP header
const fencySignature = Buffer.from(req.get("x-fency-signature"), "utf8");

// Compute signature using your secret and the request payload
const hmac = crypto.createHmac("sha256", secret);
const digest = Buffer.from("sha256=" + hmac.update(payload).digest("hex"), "utf8");

// Check whether they match, using timing-safe equality (don't use ==)
if (!crypto.timingSafeEqual(digest, fencySignature)) {
    throw new Error("Signature invalid");
}