> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arb.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Receive real-time notifications when events happen in your cases.

Webhooks let your system react to events as they happen, like a document being filed, a case moving to a new phase, or a case being closed. Instead of polling the API, you register a URL and we send you a POST request whenever something important occurs.

## How it works

1. **Register a URL** in your organization's [developer settings](https://app.arb.inc/settings/developers).
2. **Events fire** as your cases progress through the arbitration process.
3. **We send a POST request** to your URL with a JSON payload describing what happened.

Every webhook is delivered via a POST request with a JSON body and the header `x-service: webhooks.platform.arb.inc`.

## Envelope format

Every webhook event is wrapped in the same envelope structure:

<ResponseField name="id" type="string" required>
  Unique identifier for this event. Deterministic — retries of the same event produce the same ID, so you can use it for deduplication.
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  ISO 8601 timestamp of when the event occurred.
</ResponseField>

<ResponseField name="event" type="string" required>
  The event type. One of `docket_filing`, `phase_changed`, or `case_closed`.
</ResponseField>

<ResponseField name="data" type="object" required>
  Event-specific payload. Structure depends on the `event` type.
</ResponseField>

```json Example Envelope theme={null}
{
  "id": "9e9d96c0d6dd",
  "timestamp": "2025-08-15T14:32:10Z",
  "event": "docket_filing",
  "data": {
    ...
  }
}
```

## Event types

| Event                                      | Fired when                             |
| ------------------------------------------ | -------------------------------------- |
| [`docket_filing`](/webhooks/docket-filing) | A document is added to the case docket |
| [`phase_changed`](/webhooks/phase-changed) | A case transitions to a new phase      |
| [`case_closed`](/webhooks/case-closed)     | A case is closed                       |

## Retry behavior

Webhooks are delivered through a managed task queue with automatic retries. If your endpoint returns a non-2xx status code or times out (60-second limit), delivery will be retried.

The `id` field is deterministic — the same event always produces the same ID, even across retries. Use it to safely deduplicate incoming webhooks on your end.

## Best practices

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return a 2xx status code as fast as possible. Do heavy processing asynchronously after acknowledging receipt.
  </Accordion>

  <Accordion title="Deduplicate by ID">
    Store the `id` of each processed webhook. If you receive the same ID again, skip processing — it is a retry.
  </Accordion>

  <Accordion title="Verify the source">
    Webhooks include the header `x-service: webhooks.platform.arb.inc`. While not a cryptographic signature, you can use it as a basic check along with keeping your webhook URL secret.
  </Accordion>

  <Accordion title="Handle events out of order">
    Webhooks may arrive out of order. Use the `timestamp` field and your own case state to handle this gracefully.
  </Accordion>
</AccordionGroup>