Webhooks
Receive workspace events at your HTTPS endpoint and keep an integration in sync.
Subscribe to workspace events
Configure the endpoint in Settings → Webhooks or through the webhook-endpoints API. Rokn sends a POST with a JSON event envelope.
JSON · illustrative envelope
{
"id": "example-event-id",
"name": "invoice.paid",
"occurredAt": "2026-09-27T10:00:00Z",
"organizationId": "example-workspace-id",
"payload": {}
}Verify before processing
Read X-Rokn-Signature, formatted as t=<unix seconds>,v1=<hex hmac-sha256>. Compute the HMAC over the timestamp, a dot and the exact raw body bytes, using the endpoint’s signing secret.
Compare signatures with a timing-safe comparison and parse the body only after verification. Keep the endpoint secret on your server.
Handle repeat deliveries
Network errors, timeouts, 5xx responses and 408/429 responses are retried. Other 4xx responses stop delivery retries. Use the event ID to avoid processing the same event twice.