Receive webhooks
Register an endpoint and verify events from your workspace.
You can also manage endpoints and deliveries in the console.
Register the endpoint
Use a full-access API key. Management requires apiKeys:manage and is REST only, not MCP. Send Authorization: Bearer <API_KEY> and a unique Idempotency-Key per write; keep that key when retrying.
Save data.secret from the response in your secret manager. It is returned only on creation or rotation, never on reads. Choose eventTypes from the catalog. issuerRfcs is optional; omit it for all RFCs or send null on update to clear the filter.
Endpoints belong to the workspace. One API key covers all its RFCs and every event names its issuer.
POST /v1/organization/webhook-endpoints Create webhook endpoint
curl -X POST "https://api.sandbox.exac.mx/v1/organization/webhook-endpoints" \ -H "Authorization: Bearer <EXAC_API_KEY>" \ -H "Idempotency-Key: 2f6b0e7a-5c1d-4e3a-9b8f-7d4a1c9e6b52" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks", "eventTypes": [ "sat_sync.completed" ] }'Verify the signature
Install the official library with npm install standardwebhooks or pip install standardwebhooks. Exac uses Standard Webhooks with whsec_ secrets.
Pass the raw body, without parsing or reserializing it, and the webhook-id, webhook-timestamp and webhook-signature headers to the library. Disable your framework JSON parser for this route or capture the bytes before it runs. Reject the request if verification fails.
import { Webhook } from "standardwebhooks";function verifyWebhook(rawBody, headers, secret) { return new Webhook(secret).verify(rawBody, headers);}from standardwebhooks.webhooks import Webhookdef verify_webhook(raw_body, headers, secret): return Webhook(secret).verify(raw_body, headers)Acknowledge and process later
Verify, persist the event durably and return 2xx within 15 seconds. Do the work in the background. Delivery is at least once and not ordered.
Deduplicate on webhook-id, which is the event id and stays the same across retries and replays. Store that id atomically with the pending work. Do not return success if a restart would lose the event.
Retries and disabling
After failures, retry intervals are 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 10 hours, measured from each failure. Queueing and endpoint pauses can add delays.
A 410 response disables the endpoint immediately. A failed attempt after 5 days without a success also disables it. Exac emails the workspace admins. Any success resets the failure period.
Fix the receiver and update status to enabled. This resumes pending deliveries that have not expired. Deliveries that exhausted their attempts need a replay.
PATCH /v1/organization/webhook-endpoints/{endpointId} Update webhook endpoint
Rotate the secret
Save the new data.secret when rotating. Exac signs with both secrets for 1 day, so you can update the receiver without downtime. Rotating again immediately drops the oldest secret. Rotation does not enable a disabled endpoint.
POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secret Rotate webhook signing secret
Test and debug
Send a test event to the enabled endpoint. Choose eventType and issuer; the test ignores subscription filters. It uses example data with ids that do not resolve to real documents.
List deliveries to inspect their status, latest attempt and event. Page until pagination.hasMore is false. Replay creates a new delivery with the same event id through the normal queue and signing path. The event must still be retained.
POST /v1/organization/webhook-endpoints/{endpointId}/test Send test webhook event
GET /v1/organization/webhook-endpoints/{endpointId}/deliveries List webhook deliveries
Requirements and limits
HTTPS and publicly reachable addresses only. Exac does not follow redirects. At most 10 endpoints per workspace and 100 RFCs per filter. Events and deliveries expire after 30 days.
Exac only records an event if an enabled endpoint subscribes to it. There is no global feed of events from before registration.
Sandbox and production
Sandbox and production are separate deployments. Register endpoints in each with that environment's API key. The registration example uses sandbox.