---
title: "Receive webhooks"
description: "Register an endpoint and verify events from your workspace."
language: en
canonical_url: "https://exac.mx/docs/en/webhooks"
md_url: "https://exac.mx/docs/en/webhooks.md"
---

# Receive webhooks

Register an endpoint and verify events from your workspace.

[Event reference](/docs/en/webhooks/events)

[You can also manage endpoints and deliveries in the console.](/consola/webhooks)

## 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](/docs/en/api/workspace/credentials/create-webhook-endpoint)

```bash
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.

```javascript
import { Webhook } from "standardwebhooks";

function verifyWebhook(rawBody, headers, secret) {
  return new Webhook(secret).verify(rawBody, headers);
}
```

```python
from standardwebhooks.webhooks import Webhook

def 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}](/docs/en/api/workspace/credentials/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](/docs/en/api/workspace/credentials/rotate-webhook-endpoint-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](/docs/en/api/workspace/credentials/test-webhook-endpoint)

[GET /v1/organization/webhook-endpoints/{endpointId}/deliveries](/docs/en/api/workspace/credentials/list-webhook-deliveries)

[POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replay](/docs/en/api/workspace/credentials/replay-webhook-delivery)

## 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.

Complete documentation: https://exac.mx/docs/en.md
Agent documentation index: https://exac.mx/docs/en/llms.txt
