Webhooks

Webhooks let ACE notify your systems when something happens, so you do not have to poll the API. You register an HTTPS endpoint, choose the events you care about, and ACE posts a signed JSON payload to that endpoint whenever a matching event fires.

Create a subscription

Send a POST /api/v1/webhooks request with the endpoint URL and the events to subscribe to. The URL must use HTTPS.

curl -X POST "https://ace.authoritas.com/api/v1/webhooks" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/ace",
    "events": ["content.approved", "feed.ingested"],
    "description": "Production listener"
  }'

The response includes the subscription, including a secret. Store the secret. You will use it to verify that incoming deliveries really came from ACE. See the Webhooks API reference for the full request and response shapes.

Events you can subscribe to

Verify a delivery

Each delivery is signed with your subscription secret so you can confirm it is genuine before acting on it. Compute an HMAC of the raw request body using the secret and compare it to the signature header on the request. Reject any delivery whose signature does not match, and return a 2xx status only once you have accepted the event.

Retries

ACE tracks every delivery attempt. If your endpoint does not return a success status, the delivery moves through the states pending, retrying, and finally failed after the maximum number of attempts. To keep deliveries healthy:

• Respond quickly with a 2xx status, then do the heavy work asynchronously. Slow endpoints look like failures and get retried.
• Make your handler idempotent. A retry can deliver the same event more than once, so key your processing on the event id.
• Review delivery history with GET /api/v1/webhooks/{id}/deliveries. You can filter by status to find failures and see the response code ACE received. See the deliveries reference.

Manage subscriptions

• List your subscriptions: GET /api/v1/webhooks.
• Update the URL, events, or active state: PUT /api/v1/webhooks/{id}.
• Remove a subscription: DELETE /api/v1/webhooks/{id}.

To pause deliveries without losing the subscription, set is_active to false with a PUT.