Skip to main content

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": { }
}
FieldMeaning
idThe event id. Identical on every attempt and every redelivery of the same event: deduplicate on it
topicThe public topic, for example scores/updated
apiVersionv1
occurredAtWhen the platform queued the delivery, RFC 3339
platformThe platform the event comes from
installationIdYour installation on that platform
organizationIdThe organization the event is about, or null for an event about the installation itself
dataThe 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​

HeaderValue
Content-Typeapplication/json
X-Positive-TopicThe public topic, the same as the body's topic
X-Positive-Api-Versionv1
X-Positive-Event-IdThe event id, the same as the body's id
X-Positive-PlatformThe platform name
X-Positive-Organization-IdThe organization of the event, empty when there is none
X-Positive-Triggered-AtWhen this attempt was prepared, with milliseconds. Not signed
X-Positive-TimestampUnix seconds, signed
X-Positive-Signature-V2The signature to verify: Verify signatures
X-Positive-Signature-V2-PreviousThe same, made with the previous secret, for 48 hours after a rotation
X-Positive-Redelivery1 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:

Attempt12345678
Waits1 min5 min30 min2 h6 h12 h24 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.