Kit Developer Documentation

Every delivery is an HTTP POST to your endpoint’s URL with a JSON body (the “envelope”) and a set of headers.

Envelope

A delivery carries an array of events. Most deliveries carry exactly one; when many events of the same type happen at once (a bulk action in the app), Kit batches them into deliveries of up to 100 events each, so your handler should always iterate events.

{
  "delivery_id": 123456,
  "events": [
    {
      "id": "9c2e1f3a-6b7d-4e8f-a1b2-c3d4e5f60718",
      "type": "subscriber.created",
      "created": "2026-07-29T14:32:10Z",
      "data": {
        "subscriber": {
          "id": 987654,
          "first_name": "Ada",
          "email_address": "ada@example.com",
          "state": "active",
          "created_at": "2026-07-29T14:32:10Z",
          "fields": { "company": "Kit" }
        }
      }
    }
  ]
}

Field	Type	Description
`delivery_id`	integer	Identifies this POST. A retry of a failed delivery reuses it.
`events`	array	1 to 100 events, all of the same `type`.

Each event in events:

Field	Type	Description
`id`	string (UUID)	Unique id of the event. This is your deduplication key — it stays the same if the event is ever re-sent.
`type`	string	The event type.
`created`	string	ISO 8601 UTC timestamp of when the event occurred (not when it was delivered).
`data`	object	The event payload. Its shape depends on `type` — see event types.

A delivery never mixes event types and never carries more than 100 events. Kit also splits a batch once it would pass roughly 512 KB of event payload, so most deliveries stay well under that; a single event larger than 512 KB is still delivered on its own rather than dropped.

Headers

Header	Description
`Content-Type`	Always `application/json`.
`X-Kit-Delivery`	The `delivery_id`, matching the body.
`X-Kit-Signature`	Timestamped HMAC signature of the raw body — see Verifying signatures.
`User-Agent`	`Kit-Webhooks/2.0`.

HTTP behavior

Deliveries are always POST requests.
Respond with any 2xx status to acknowledge. Kit reads only the status code, not the response body.
Any non-2xx response, a connection failure, or a timeout marks the delivery failed and schedules a retry. A retry re-POSTs the entire events array, so process each event idempotently by its id.
Sign or validate against the raw request body exactly as received — don’t re-serialize the JSON first, or the signature won’t match.

Your endpoint must be a public HTTP(S) URL. Kit blocks delivery to private, internal, or loopback addresses.

Related topics

Webhooks overview OAuth authorization Retries Verifying signatures Changelog