Verifying signatures

Each PUSH delivery is signed so you can prove it came from Endl. Always verify before acting on a webhook.

Delivery headers

Header	Description
`X-WEBHOOK-SIGNATURE`	128 lowercase hex characters — HMAC-SHA512 over `timestamp + "." + body`.
`X-WEBHOOK-TIMESTAMP`	ISO-8601 UTC with three fraction digits. Also covered by the signature.
`X-WEBHOOK-EVENT-ID`	The event id. Use it as your idempotency key.

Three things to get right. It is SHA-512, not SHA-256. The hex is lowercase. And you must HMAC the raw received body bytes — parsing the JSON and re-serializing it changes those bytes and breaks the signature.

Example delivery

POST /webhooks/endl HTTP/1.1
Host: api.acme.com
Content-Type: application/json
User-Agent: Endl-Webhooks/1.0
X-WEBHOOK-EVENT-ID: 72949438-265e-5aa7-8e6c-56af893a58eb
X-WEBHOOK-TIMESTAMP: 2026-05-22T15:09:58.500Z
X-WEBHOOK-SIGNATURE: d1d6553c34daa198aa8f259715efbd396f0c8a0658a4484f281d15536f889658e79f2e4538258899a4fea5500b0b7e196d2bf1a147e84a09f796291b76512dc5

{"eventId":"72949438-265e-5aa7-8e6c-56af893a58eb","eventType":"payout.completed","eventCategory":"payout","eventCreatedAt":"2026-05-22T15:09:58.500Z","version":"2026-09.1","data":{"id":"txn_c7d8e9f0","customerId":"cus_9f2c1a44","destinationAmount":"1387.50","destinationCurrency":"USD","fxRate":"0.9250","sourceAmount":"1500.00","sourceCurrency":"AED","status":"COMPLETE","subStatus":"TRANSACTION_PROCESSED_SUCCESSFULLY"}}

The body is a single compact line, and the signature covers exactly those bytes. Its top level is always eventId, eventType, eventCategory, eventCreatedAt, version and data — six keys, frozen across schema versions. Only data is version-specific. Inside data come two metadata keys, then the producer’s own fields in sorted key order. data.id is prefixed — txn_, acct_, cus_ — and that prefix is the only thing that says what the event is about. data.customerId is omitted entirely when the event carries no customer. Every leaf value is a string, amounts included, and null-valued fields are omitted rather than sent as null. No subscription id is sent. Four more rules govern how data is rendered, and all four matter if you are generating types from a delivery rather than reading this page:

Rule	Consequence
Payload keys are sorted	Field order is stable across deliveries of the same type.
A payload field colliding with `id` or `customerId` is dropped	The metadata value wins. A producer cannot shadow either key.
Nested objects and arrays are supported, recursively	The same rules apply at every depth — sorted keys, string leaves, nulls omitted.
There is no gateway allowlist	Every key the producing service wrote is published.

Because there is no allowlist, treat the event catalogue as the current shape rather than a closed schema. Handle an unrecognised eventType — or an extra field inside data — gracefully instead of rejecting the delivery.

Verify the signature

import hmac, hashlib

def verify_webhook(raw_body: bytes, headers: dict, secrets: list[str]) -> bool:
    ts = headers["X-WEBHOOK-TIMESTAMP"]        # "2026-09-02T12:34:56.789Z"
    sig = headers["X-WEBHOOK-SIGNATURE"]       # 128 lowercase hex chars
    signed = ts.encode("utf-8") + b"." + raw_body
    for secret in secrets:                     # current, plus previous during rotation
        expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha512).hexdigest()
        if hmac.compare_digest(expected, sig):
            return True
    return False

const crypto = require("crypto");

function verifyWebhook(rawBody, headers, secrets) {
  const ts = headers["x-webhook-timestamp"];
  const sig = headers["x-webhook-signature"];
  const signed = Buffer.concat([Buffer.from(ts + "."), rawBody]);
  return secrets.some((secret) => {
    const expected = crypto.createHmac("sha512", secret).update(signed).digest("hex");
    const a = Buffer.from(expected), b = Buffer.from(sig);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

import (
    "crypto/hmac"
    "crypto/sha512"
    "encoding/hex"
)

func VerifyWebhook(rawBody []byte, ts, sig string, secrets []string) bool {
    signed := append([]byte(ts+"."), rawBody...)
    for _, secret := range secrets {
        mac := hmac.New(sha512.New, []byte(secret))
        mac.Write(signed)
        expected := hex.EncodeToString(mac.Sum(nil))
        if hmac.Equal([]byte(expected), []byte(sig)) {
            return true
        }
    }
    return false
}

All three examples compare in constant time and accept a list of secrets. That list is what makes a secret cutover safe — see below.

Replay and secret cutovers

The timestamp is covered by the signature, so you can trust it: reject any delivery whose X-WEBHOOK-TIMESTAMP is more than about five minutes old. A captured request cannot be replayed with a fresh timestamp, because rewriting it invalidates the signature. There is no rotate endpoint. The signing secret is returned once, when the subscription is created, and cannot be read back afterwards. If it is lost, delete the subscription and create a new one — that mints a fresh secret bound to a new subscription id, and leaves the old one’s delivery history intact. Each subscription has its own secret, so moving traffic to a new receiver means both secrets are briefly live while the old subscription drains. Write your verifier against a list of secrets from the start, as the examples above do, and drop the retired one once nothing signed under it is still in flight.

secretHint is a masked form of the current secret — whsec_… plus its last 4 characters. It exists so a support ticket can answer “which secret are you signing with?” without either side handling the secret itself: you compare the hint against your stored copy, and it either matches or you are verifying with the wrong one. Comparing hints is safe to paste into a ticket. Comparing secrets is not.A PULL subscription has neither a webhook_secret nor a secretHint — a PULL feed is never signed.

Deduplicate on X-WEBHOOK-EVENT-ID. Retries and manual sends can deliver the same event more than once, and a receiver that is idempotent on the event id handles all of it for free.

Introduction

Endpoints

Verifying signatures

Delivery headers

Example delivery

Verify the signature

Replay and secret cutovers

​Delivery headers

​Example delivery

​Verify the signature

​Replay and secret cutovers

Delivery headers

Example delivery

Verify the signature

Replay and secret cutovers