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 page lists what each event carries, and 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. The platform creates the subscriptions when the app is installed or consents again, and only for the topics your granted 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:
{
"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 |
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, <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 |
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 rather than assuming the last delivery is the latest state: scores/updated tells you something changed, and the API gives you the current values.