Webhook Security
Webhooks
endpoints registered via the backoffice. Every delivery is signed with Ed25519
so consumers can confirm the request originated from the CMS and was not
tampered with in transit.
Delivery format
POST with a JSON body and two custom headers:| Field | Type | Description |
|---|---|---|
id | UUID v4 | Unique delivery id. Stable across Oban retries — use it for idempotency. |
event_name | string | Event identifier (e.g. participant_created). |
sent_at | ISO 8601 UTC | Moment the CMS enqueued the delivery. Use it for replay protection. |
data | object | Event payload. Shape depends on event_name. |
| Header | Description |
|---|---|
x-omerlo-webhook-signature | Base64-encoded Ed25519 signature over the raw request body. |
x-omerlo-webhook-key-id | Identifier of the signing key (currently v1). Lets the CMS rotate keys without breaking consumers. |
Public key distribution
GET https://<cms-host>/.well-known/omerlo-webhook-public-key{
"algorithm": "ed25519",
"keys": [
{ "id": "v1", "public_key": "<base64-encoded 32-byte Ed25519 public key>" }
]
}401 response. Thekeys array is plural so additional keys can appear during a rotation window.Verifying a delivery
1.
re-serialize a parsed JSON object — key ordering and whitespace would
differ and the signature would no longer match.
2.
x-omerlo-webhook-key-id header.3.
x-omerlo-webhook-signature header.4.
(public_key, raw_body, signature).5.
sent_at is older than 5 minutes (replay protection).6.
id was already processed (idempotency).7.
2xx once the event is safely persisted; any other statustriggers an Oban retry.
Modified at 2026-06-29 05:25:01