Events and webhook signatures
The implemented signature contract and verification steps.
Register an HTTPS receiver with POST /v1/webhook_endpoints, using a secret API key and
an Idempotency-Key header:
{
"url": "https://your-app.example/webhooks/hermos",
"enabled_events": ["health.changed"],
"include_historical": false
}Use ["*"] to subscribe to all merchant events. Internal event types cannot be subscribed to.
Dashboard sessions with Owner, Admin or Developer authority can also manage endpoints
after a sign-in within the last ten minutes. Agent keys can read endpoints but cannot change them.
Store the returned secret securely immediately. It appears only in the initial create or
roll response; GET /v1/webhook_endpoints and GET /v1/webhook_endpoints/{id} never return it.
An idempotent replay returns only issuance metadata, so a lost secret requires a new roll.
To rotate, POST {} to /v1/webhook_endpoints/{id}/roll_secret with a new Idempotency-Key.
Store the new secret; deliveries carry signatures under both secrets for 24 hours, until
secret_rotation.previous_expires_at. For emergency revocation, send
{"expire_previous":"now"} instead: subsequent signing uses only the new secret immediately.
The receiver must also stop accepting the compromised secret.
Only one previous secret is retained. A second roll inside the 24-hour overlap drops the
older previous secret immediately and retains the current secret as the new previous secret
for another 24 hours. With expire_previous: "now", no previous secret is retained.
Update an endpoint with PATCH /v1/webhook_endpoints/{id}. Send at least one of
url, enabled_events, include_historical, or status; omitted fields keep their values.
URLs must meet the same HTTPS and public-address restrictions as create. enabled_events
accepts 1–100 unique merchant event types (at most 200 characters each), or *.
These changes never rotate or return a signing secret.
Send {"status":"disabled"} to pause delivery. On an auto_disabled endpoint, PATCH
relabels its status as disabled. Pending and retrying deliveries are canceled
in the same transaction. A worker that already passed its status check can still finish within
its existing claim lease (at most 30 seconds); disabling does not recall an in-flight request.
Disabled endpoints continue to count toward the limit of 16 endpoints per company and mode;
disable unused endpoints; deletion is coming.
Send {"status":"enabled"} to PATCH, or call POST /v1/webhook_endpoints/{id}/enable
with no body, to re-enable a disabled endpoint. The enable route also recovers an
auto_disabled endpoint after an outage: it sets health to healthy and clears
failing_since. Delivery resumes from the next event. Canceled deliveries and events
published while disabled are not resent. Enabling an already enabled endpoint leaves
its current health unchanged. You cannot set status to auto_disabled yourself.
All these writes require an Idempotency-Key and the same secret-key or freshly stepped-up
dashboard authority as create. Their idempotent replays return the original response without
a secret. Restricted, publishable and agent keys cannot perform these writes.
Event types are still being added. The signing and verification contract is:
| Header | Value |
|---|---|
webhook-id | Non-empty message ID. |
webhook-timestamp | Non-negative Unix epoch seconds as a decimal integer. |
webhook-signature | Space-separated v1,<base64 signature> entries. |
The signing secret is whsec_ followed by canonical Base64-encoded key bytes. Newly generated
secrets contain 32 random bytes. Decode the secret after removing whsec_.
Sign the exact string id.timestamp.body using HMAC-SHA256 with those decoded key bytes.
Here id and timestamp are the header values, and body is the original body string.
Encode the digest with standard Base64 and prefix it with v1,.
To verify a delivery:
- Preserve the original body text before JSON parsing. Do not reserialize it.
- Read the three headers case-insensitively and reject missing or malformed values.
- Check that the timestamp is within 300 seconds of the current time. Both boundary values are accepted by the default verifier.
- Compute the HMAC over the same
id.timestamp.bodytext for each trusted secret. - Decode valid
v1signatures and compare 32-byte digests using a constant-time comparison. Accept when any trusted secret matches any supplied signature.
The helpers support secret rotation. During an overlap period, signing uses the current and previous secrets; the previous secret stops signing at the exact expiry instant. Verification accepts an explicit list of trusted secrets. The verifier checks signatures and timestamp freshness; persistent webhook-ID replay deduplication is not implemented by this helper.