# Webhooks

> The v1 envelope every webhook uses, its headers, the delivery rules and how failed deliveries are retried and redelivered.

Source: https://developers-staging.foodpilot.tech/build/webhooks

In this page you will learn what your endpoint receives, how a delivery is retried, and which guarantees you can rely on. The [topics](/build/webhooks/topics) page lists what each event carries, and [Verify signatures](/build/webhooks/verify-signatures) shows how to check a request.

## Subscribe

List the topics you want, with the HTTPS endpoint of each, in the `webhooks` field of your [manifest](/build/manifest). The platform creates the subscriptions when the app is installed or consents again, and only for the topics your granted [scopes](/build/scopes) allow. A subscription only receives events about the organizations the installation covers.

## The envelope

Every delivery is a `POST` whose body is one JSON object, whatever the topic:

```json
{
  "id": "0194e328-a9a5-771c-9d8d-dd28118a4c25",
  "topic": "scores/updated",
  "apiVersion": "v1",
  "occurredAt": "2026-11-14T10:00:05+01:00",
  "platform": "acme",
  "installationId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "organizationId": 12,
  "data": { }
}
```

| Field | Meaning |
|---|---|
| `id` | The event id. Identical on every attempt and every redelivery of the same event: deduplicate on it |
| `topic` | The public topic, for example `scores/updated` |
| `apiVersion` | `v1` |
| `occurredAt` | When the platform queued the delivery, RFC 3339 |
| `platform` | The platform the event comes from |
| `installationId` | Your installation on that platform |
| `organizationId` | The organization the event is about, or `null` for an event about the installation itself |
| `data` | The topic's content, documented in [topics](/build/webhooks/topics) |

There is no other top-level field. Inside `data`, ignore any field you do not know: version 1 may add some.

The shape of every topic is a [JSON Schema](https://json-schema.org), `<topic>.schema.json`, committed with the platform and versioned with it. A change that breaks a schema is a version 2.

## Headers

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `X-Positive-Topic` | The public topic, the same as the body's `topic` |
| `X-Positive-Api-Version` | `v1` |
| `X-Positive-Event-Id` | The event id, the same as the body's `id` |
| `X-Positive-Platform` | The platform name |
| `X-Positive-Organization-Id` | The organization of the event, empty when there is none |
| `X-Positive-Triggered-At` | When this attempt was prepared, with milliseconds. Not signed |
| `X-Positive-Timestamp` | Unix seconds, signed |
| `X-Positive-Signature-V2` | The signature to verify: [Verify signatures](/build/webhooks/verify-signatures) |
| `X-Positive-Signature-V2-Previous` | The same, made with the previous secret, for 48 hours after a rotation |
| `X-Positive-Redelivery` | `1` when an administrator sent the event again |

The signature headers of the older format (`X-Positive-Signature` and `-Previous`) are also sent. New code should use the V2 ones.

## What counts as success

Answer with any `2xx` status within 3 seconds of silence and 5 seconds in all. Do the work afterwards: store the event, answer, then process it. Any other answer, a timeout or a connection error is a failed attempt, and so is a `4xx`: the platform retries them all.

## Retries

A failed attempt is retried with a growing delay:

| Attempt | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|---|---|---|---|---|---|---|---|---|
| Waits | | 1 min | 5 min | 30 min | 2 h | 6 h | 12 h | 24 h |

That is 8 attempts over about 45 hours. After the last one, the event is not sent again by itself. Every attempt keeps the same event `id` and the same body, so a retry after your server did receive the first one is a duplicate to ignore.

An address that resolves to a private or loopback network is refused without retry.

## Disabling

After 20 consecutive failed attempts, the platform deactivates that subscription. The administrator of the installation sees the failures, and can have the platform send a failed event again. Fix your endpoint first: a redelivery is refused if the app is not active, the subscription is inactive, or the event was already received.

## Redelivery

An administrator can send a failed event again from the installation's delivery log. The platform queues the same event: same `id`, same body, the `X-Positive-Redelivery: 1` header, a fresh timestamp and a signature made with the current secret. Deduplicate on the `id`: if you have handled the event, answer `2xx` and do nothing.

## Order

The platform does not promise the order of events. Use `occurredAt` and the data you read back from the [App API](/build/app-api) rather than assuming the last delivery is the latest state: `scores/updated` tells you something changed, and the API gives you the current values.
