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

# Protocol and Delivery

## Transport

| Aspect                 | Specification                                |
| ---------------------- | -------------------------------------------- |
| **HTTP method**        | POST                                         |
| **Protocol**           | HTTPS only                                   |
| **Timeout**            | Response expected within 15 seconds          |
| **Batching**           | Not supported                                |
| **Ordering**           | Not guaranteed                               |
| **Delivery semantics** | At-least-once                                |
| **Success**            | Consumer must respond with a 2XX status code |

## Retry behaviour

By default, TechWolf retries delivery when your endpoint returns one of these
status codes: **408**, **429**, **500**, **502**, **503**, **504**, or when a
request fails due to **timeouts** or **other network errors**.

* **Attempts:** up to three retries per delivery
* **Backoff:** exponential between attempts
* **Retry-After:** if your endpoint responds with a `Retry-After` header,
  TechWolf uses that value (delay-seconds or HTTP-date per RFC 7231) instead of
  the default backoff

## Source IP addresses

All webhook requests are sent from a fixed, static set of IP addresses.
Allowlist the IPs for your region so that your endpoint accepts delivery from
TechWolf. See
[IP Addresses <Icon icon="link" iconType="solid" />](/integrations/reference/ip-addresses)
for the current list.

## Event format

All webhook payloads follow the
[CloudEvents 1.0](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md)
specification.

### Base structure

```json theme={null}
{
  "specversion": "1.0",
  "type": "<event-type>",
  "source": "<resource-url>",
  "id": "<id>",
  "time": "<iso-8601-timestamp>",
  "data": {
    ...
  }
}
```

### Field semantics

| Field         | Description                                                                                                                                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `specversion` | CloudEvents spec version (1.0).                                                                                                                                                                                                     |
| `type`        | Event type and version; use to route the event and to know which API to call for the full state.                                                                                                                                    |
| `source`      | URL of the resource that changed.                                                                                                                                                                                                   |
| `id`          | Unique per event. Use to deduplicate, since delivery is at-least-once.                                                                                                                                                              |
| `time`        | When the change occurred (ISO 8601). Useful for ordering or idempotency.                                                                                                                                                            |
| `data`        | Identifiers and metadata to locate the change and call the API (e.g. tenant, `external_id`, `operation_type`, `external_vendor`). Use these to fetch the full state from the API; the payload does not contain the resource itself. |

## Request headers

Unless you request or configure otherwise, each webhook request includes the
following headers:

| Header                  | Description                                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`          | `application/json`                                                                                                                          |
| `User-Agent`            | `TechWolf-Webhooks/1.0`                                                                                                                     |
| `X-Event-Id`            | Same as the event `id` in the body; used when verifying the signature and for deduplication.                                                |
| `X-Tenant`              | Tenant name; used when verifying the signature and when calling the API.                                                                    |
| `X-Signature-Timestamp` | Time the message was signed (seconds since Unix epoch). Used when verifying the signature and to reject stale requests (replay protection). |
| `X-Signature-V1`        | Hex-encoded signature(s). May contain multiple comma-separated values during key rotation; at least one must verify.                        |

See [Security](/integrations/webhooks/security) for how to verify the signature.