Receive updates automatically

Use webhooks to receive events without repeatedly checking the API.

A webhook sends an HTTP request to your integration when an event happens. You need a receiving service with an HTTPS URL and a key with webhooks:write.

1. Prepare the receiver URL for your integration. Use its webhook endpoint, not its homepage.
2. Call Create webhook endpoint, selecting supported event names from the endpoint's event catalogue.
3. Store the returned signing secret securely. It is shown only once.
4. Verify each incoming X-Acquisity-Signature header before trusting the event. Its format is t=<unix>,v1=<hmac_sha256(t.body)>; verification must use the original request body, not re-serialized JSON. Also check that the signed t timestamp is recent (for example, within five minutes of your server clock) and reject older timestamps to prevent replay attacks.
5. After signature and timestamp validation, deduplicate using the body’s stable id (also sent as Idempotency-Key). Persist processed IDs and ignore duplicates before applying effects that must happen only once. A recent timestamp alone does not prevent duplicate delivery within the accepted time window.
6. Check the registered receiver against a representative event before relying on it for your workflow.

Success: your receiver accepts a correctly signed event and processes it. Registration alone does not prove delivery. Treat event handling as repeatable; do not assume exactly-once delivery or immediate arrival.

Personal-token callers also need to be a workspace owner or admin. A receiver error is separate from API authentication: verify that the URL accepts webhook POST requests and that any receiver authentication is configured correctly.