> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aurasos.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aurasos.com/_mcp/server.

# 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

1. Stand up an HTTPS endpoint that accepts `POST` requests.
2. Register the endpoint and the events you want — in the AURA portal under
   **Integration → Webhooks**, via the [API](#registering-an-endpoint), or by
   asking your AURA contact. Each customer source has one active webhook;
   registering again replaces it.
3. Receive a payload for each subscribed event. Every payload is a JSON object
   with a `message` field naming the event, plus the relevant entity
   (`callout`, `customer`, or `subscription`).

```mermaid
flowchart LR
    A[Provide endpoint URL] --> B[Select events]
    B --> C{Event occurs?}
    C -- Yes --> D[AURA POSTs the payload to your URL]
    D --> E[Process the event]
```

## Event types

Subscribe to any combination of the events below.

### Callouts

| Event                                 | Fires when                                               | Triggered by     |
| ------------------------------------- | -------------------------------------------------------- | ---------------- |
| `NEW_CALLOUT`                         | A callout is created                                     | Your integration |
| `RESPONDER_MANUALLY_DISPATCHED`       | A controller manually dispatches a responder             | AURA             |
| `RESPONDER_ACKNOWLEDGED_CALLOUT`      | A responder is auto-dispatched (with ETA)                | AURA             |
| `RESPONDER_ARRIVED_ON_SCENE`          | A responder arrives on scene                             | AURA             |
| `RESPONDER_COMPLETED`                 | A responder completes the response                       | AURA             |
| `CALLOUT_OWNED`                       | A controller takes ownership of the callout              | AURA             |
| `CALLOUT_EVENTS_CHANGED`              | The callout's event stream changes (e.g. a chat message) | Either           |
| `CALLOUT_SOFT_CANCELLED_BY_CUSTOMER`  | The customer soft-cancels                                | Your integration |
| `CALLOUT_NO_LONGER_REQUIRES_RESPONSE` | The callout is cancelled / responder stood down          | Your integration |
| `CALLOUT_CLOSED`                      | The callout is closed                                    | AURA             |

> **Note**
>
> `RESPONDER_ACKNOWLEDGED_CALLOUT_WITH_ETA` is **deprecated** — existing
> registrations still work, but use `RESPONDER_ACKNOWLEDGED_CALLOUT` instead.

### Subscriptions

| Event                           | Fires when                               |
| ------------------------------- | ---------------------------------------- |
| `SUBSCRIPTION_CREATED`          | A subscription is activated              |
| `SUBSCRIPTION_UPDATED`          | A subscription changes (e.g. dependants) |
| `SUBSCRIPTION_CANCELLED`        | A subscription is cancelled              |
| `SUBSCRIPTION_CANCELLED_FAILED` | A cancellation fails                     |

### Customers

| Event                                | Fires when                                          |
| ------------------------------------ | --------------------------------------------------- |
| `CREATED_CUSTOMER`                   | A customer is created                               |
| `CREATED_CUSTOMER_TERMS`             | A customer accepts white-label terms and conditions |
| `UPDATED_CUSTOMER`                   | A customer is updated                               |
| `UPDATED_CUSTOMER_WITH_SUBSCRIPTION` | A customer is updated together with a subscription  |

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:

```json
{
  "message": "NEW_CALLOUT",
  "callout": {
    "id": 81290,
    "status": "created",
    "responseTypeId": 1,
    "customerId": 184569,
    "customer": { "id": 184569, "name": "...", "mobile": "..." },
    "location": { "latitude": "-26.10911", "longitude": "28.053037" }
  }
}
```

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](/api-reference/webhooks).

The endpoint URL must be **HTTPS**. Each customer source has a single active
webhook, so registering again replaces the previous configuration.

```json
{
  "url": "https://your-server.example.com/api/webhooks/events",
  "events": ["NEW_CALLOUT", "CALLOUT_CLOSED"],
  "method": "webhook",
  "headers": { "authorization": "Bearer <your-token>" }
}
```

## Securing deliveries

* **Custom headers** — any headers you register (e.g. an `Authorization` token)
  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:

  | Environment | Source IPs                                         |
  | ----------- | -------------------------------------------------- |
  | Staging     | `34.247.224.1`, `54.194.225.114`, `54.78.115.129`  |
  | Production  | `54.220.143.196`, `34.251.163.85`, `34.246.93.167` |

## Handling deliveries

* **Respond quickly** with a `2xx` and process asynchronously.
* **Be idempotent** — the same event may arrive more than once.
* **Key on `message` + the entity `id`** to deduplicate and route.

> **Warning**
>
> 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](/api-reference/callouts/get-callout-by-id) for any incident
> where the expected events did not arrive.

## Testing

Point a webhook at a mock endpoint (for example [webhook.site](https://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:

| Simulator step                             | Webhook event                         |
| ------------------------------------------ | ------------------------------------- |
| Responder Dispatched (automated/tech flow) | `RESPONDER_ACKNOWLEDGED_CALLOUT`      |
| Supplier Dispatched (manual flow)          | `RESPONDER_MANUALLY_DISPATCHED`       |
| Responder Arrived                          | `RESPONDER_ARRIVED_ON_SCENE`          |
| Responder Completed                        | `RESPONDER_COMPLETED`                 |
| Close Callout                              | `CALLOUT_CLOSED`                      |
| Response Cancelled                         | `CALLOUT_NO_LONGER_REQUIRES_RESPONSE` |

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.

> **Note**
>
> 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.