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

# Webhook Overview

> Configure and receive outbound event notifications.

Simply Tokenized can **POST event notifications** to your HTTPS endpoint when resources change in your tenant. These are **outbound webhooks** — we call your server, not the other way around.

## Setup

1. Open **Administration → API Access → Webhooks** in the Asset Manager dashboard
2. Create a webhook with your HTTPS endpoint URL
3. Select the events you want to receive
4. Copy the **signing secret**

## Delivery pipeline

```mermaid theme={null}
flowchart LR
  event[Business event] --> outbox[Webhook outbox]
  outbox --> queue[SQS queue]
  queue --> deliver[Delivery worker]
  deliver --> endpoint[Your HTTPS endpoint]
  deliver --> log[Delivery log]
```

1. Events are written to a **webhook outbox** table
2. A message is queued to SQS for delivery
3. The delivery worker POSTs to your URL with signed headers
4. Each attempt is logged (status code, response body, success/failure)
5. Failed deliveries are retried automatically

## Reliability

| Setting                  | Value                                                |
| ------------------------ | ---------------------------------------------------- |
| Request timeout          | 5 seconds                                            |
| Max retries per delivery | 5                                                    |
| Retry delay              | 60s first retry, then +40s each time                 |
| Auto-disable threshold   | 5 consecutive delivery failures                      |
| Failure notifications    | Email sent to tenant admins on every failed delivery |

### Delivery failures

A delivery counts as a **failure** when:

* Your endpoint does not respond within **5 seconds**
* Your endpoint returns a **non-2xx** HTTP status
* The connection cannot be established (DNS, TLS, or network error)

Failed deliveries are retried automatically (up to **5 attempts** per outbox event). Each failed attempt is logged with the HTTP status code and response body.

### Retry schedule

Retries use **incremental backoff**. The first retry waits **60 seconds**; each subsequent retry adds **40 seconds**:

| After failed attempt | Wait before next retry |
| -------------------- | ---------------------- |
| 1st                  | 60 seconds             |
| 2nd                  | 100 seconds            |
| 3rd                  | 140 seconds            |
| 4th                  | 180 seconds            |

Formula: `60 + (attempt − 1) × 40` seconds.

After the **5th** failed attempt, the event is not retried further and may move to a dead-letter queue for investigation.

### Failure notifications

Tenant administrators receive an **email on every failed delivery**. The email includes:

* Webhook name and URL
* Event type that failed to deliver
* HTTP status (or `unreachable` if no response)
* Current consecutive failure count (e.g. `3 of 5`)

For failures **1–4**, the email warns that the webhook will be **automatically disabled** after **5 consecutive** failures.

On the **5th consecutive failure**, the email confirms the webhook **has been disabled**.

### Auto-disable

After **5 consecutive delivery failures** for the same webhook:

1. The webhook status is set to **DISABLED**
2. No further events are delivered to that endpoint
3. Tenant administrators receive a final email confirming the disable

A successful delivery (2xx response) **resets** the consecutive failure counter to `0`.

Re-enable the webhook in **Administration → API Access → Webhooks** after fixing your endpoint. Verify your server accepts signed `POST` requests and returns `2xx` within the timeout.

## Request format

Every delivery is an HTTP `POST` with a JSON body:

```json theme={null}
{
  "id": "131a1559-3723-4c6b-b133-f5d5747c2bfa",
  "type": "order.created",
  "data": { ... }
}
```

## Headers

| Header               | Description                               |
| -------------------- | ----------------------------------------- |
| `content-type`       | `application/json`                        |
| `x-st-event`         | Event type (e.g. `order.created`)         |
| `x-st-webhook-id`    | Outbox delivery ID                        |
| `x-st-signature`     | HMAC-SHA256 hex signature of the raw body |
| `x-st-signature-alg` | `HMAC_SHA256_HEX`                         |

## Next steps

<CardGroup cols={2}>
  <Card title="Signature verification" icon="shield-check" href="/webhooks/signature-verification">
    Verify that events are authentic.
  </Card>

  <Card title="Event catalog" icon="list" href="/webhooks/events">
    All supported events and payload fields.
  </Card>
</CardGroup>