Webhooks
Webhooks let your integration receive real-time notifications as events happen
across callouts, responders, customers, and subscriptions — instead of
polling. You register an endpoint URL and the events you care about, and AURA
sends a POST with the event payload whenever one occurs.
How it works
- Stand up an HTTPS endpoint that accepts
POSTrequests. - Register the endpoint and the events you want — in the AURA portal under Integration → Webhooks, via the API, or by asking your AURA contact. Each customer source has one active webhook; registering again replaces it.
- Receive a payload for each subscribed event. Every payload is a JSON object
with a
messagefield naming the event, plus the relevant entity (callout,customer, orsubscription).
Event types
Subscribe to any combination of the events below.
Callouts
RESPONDER_ACKNOWLEDGED_CALLOUT_WITH_ETA is deprecated — existing
registrations still work, but use RESPONDER_ACKNOWLEDGED_CALLOUT instead.
Subscriptions
Customers
Registering with an event name outside this list is rejected with 400.
Payload shape
Each delivery is a JSON object keyed by message (the event name) plus the
entity it concerns. For example, a callout event:
Responder-related callout events additionally carry an incidentInformation
block with dispatch details (responder, supplier, response type, classification,
and timestamps for dispatch / arrival / completion).
Registering an endpoint
You can manage your webhook two ways:
- AURA portal — under Integration → Webhooks, set the endpoint URL, the events to subscribe to, and any custom headers.
- API — see Register a webhook.
The endpoint URL must be HTTPS. Each customer source has a single active webhook, so registering again replaces the previous configuration.
Securing deliveries
-
Custom headers — any headers you register (e.g. an
Authorizationtoken) are included on every delivery, so your endpoint can authenticate the caller. -
IP allowlisting — webhook requests are sent from fixed AURA IP addresses. Allowlist them if your endpoint restricts inbound traffic:
Handling deliveries
- Respond quickly with a
2xxand process asynchronously. - Be idempotent — the same event may arrive more than once.
- Key on
message+ the entityidto deduplicate and route.
Deliveries are attempted once. If your endpoint is down or returns an error, the event is not retried — don’t treat the webhook stream as a complete ledger. Reconcile by polling Get a callout for any incident where the expected events did not arrive.
Testing
Point a webhook at a mock endpoint (for example webhook.site) during development, then trigger events through the API — create a customer, create a callout, activate a subscription — and confirm the payloads arrive. Switch to your real endpoint once verified.
Testing with the Responder Simulator
The staging Responder Simulator emits the same webhook events as a live response, so you can exercise your receiver end to end without AURA involvement. Create a callout through the API, then step it through the simulator:
Dispatch, arrival, and completion also add entries to the callout’s event
stream, so CALLOUT_EVENTS_CHANGED subscribers receive those too. Closing a
callout also produces the resolution report, as it does in production.
Register your webhook before creating the test callout. Webhook delivery for a callout is based on the registration in place when that callout was created, so events for a callout created earlier are not delivered.
