Webhook delivery

Every Flint webhook uses the same request shape, envelope, and retry schedule, whatever the event type. To build and register a handler, follow the Webhooks guide. For each event type and its data payload, see the event catalog.

Delivery contract#

Endpoint URLs must use HTTPS. Sandbox endpoints and partner endpoints restricted to test mode may point at a host that isn't live yet. Live endpoints and partner endpoints that include live mode must resolve to public IP addresses when you register or change them. HTTPS, localhost, and private IP checks still apply in test mode. Before every attempt, Flint resolves the hostname and checks every address: a DNS failure reports webhook_dns, and a private or local address reports webhook_blocked_target.

An endpoint belongs to the mode and sandbox of the API key that created it, and receives only that environment's events.

Delivery headers#

POST /webhooks/flint HTTP/1.1
Content-Type: application/json
User-Agent: Flint-Webhooks/1.0
Authorization: Bearer <Flint-signed JWT>
Flint-Webhook-Endpoint-Id: whep_1kmn0aExample
webhook-id: whev_1kmn0aExample
webhook-timestamp: 1783090410

Header names are case-insensitive. The event type is in the body's event_type; route on it after you verify the signature.

JWT signing#

New endpoints default to "signing_methods": ["jwt"]. Each attempt carries a fresh ES256 JWT with header typ: flint-webhook+jwt and a kid naming a key in Flint's JWKS at https://api.withflintpay.com/.well-known/jwks.json.

The token has no sub. To verify a delivery:

• Require ES256, typ: flint-webhook+jwt, the issuer above, and an aud from your own list of endpoint IDs.
• Check iat and exp with at most 60 seconds of leeway, and reject a token whose lifetime exceeds 300 seconds.
• Hash the raw body and compare it with body_sha256 in constant time before you parse the JSON. Do this even when a gateway in front of you verifies the JWT, because verifying the token alone doesn't check the body.
• Deduplicate on webhook_event_id, not jti: every retry has a new token and attempt ID.
• Honor the JWKS Cache-Control, cache keys for at most 24 hours, refetch at most once a minute for an unknown kid, and never pin a key ID.

The Step 4 verifiers in the Webhooks guide, with the Node and PHP SDKs or without one, implement all of these.

With ["jwt", "hmac"], each delivery carries both Authorization and webhook-signature. Flint never sends a JWT endpoint a delivery without its JWT, and never falls back to HMAC alone. If Flint can't sign, a test event or resend returns 503 SERVICE_UNAVAILABLE, and an automatic delivery waits and tries again without using one of its 9 attempts. To move an existing endpoint between methods, change its signing methods.

Event body#

{
  "webhook_event_id": "whev_1kmn0aExample",
  "event_type": "payment_intent.succeeded",
  "event_source": "merchant",
  "payload_version": 2,
  "api_version": "2026-09-07",
  "mode": "test",
  "sandbox_id": "test_1kmn0aExample",
  "merchant_id": "mer_1kmn0aExample",
  "created_at": "2026-07-03T14:53:30Z",
  "test": false,
  "request": {
    "id": "req_01KWM638WGDX5RZ6THJCQBZCEV",
    "idempotency_key": "confirm-payment-1kmn0a-001"
  },
  "data": {
    "object": {
      "payment_intent_id": "pi_1kmn0aExample",
      "status": "succeeded",
      "amount_money": {"amount": 2500, "currency": "USD"},
      "order_id": "ord_1kmn0aExample"
    }
  }
}

The object above is abbreviated. A delivery carries the whole resource as its GET returns it, without expansions and apart from the few caller-specific fields the event payload guide lists under fields webhooks leave out.

Which API version a delivery uses#

Every event records the API version it was created at. Each attempt renders data at the older of that version and the endpoint's api_version at the moment of the attempt; an endpoint set to "default" uses the merchant's default version then. Flint never converts an event to a newer version than it was recorded at.

Because each attempt chooses again, a retry or resend that follows a change to the endpoint's api_version can arrive at a different version from the first attempt, with the same webhook_event_id. Read api_version before you parse data. API versions and upgrades covers moving endpoints between versions.

Partner app envelope#

Endpoints owned by a partner app receive the same data in a partner envelope. It has partner_app_id instead of mode, merchant_id, and request, and a source object that says which merchant and install the event concerns. The required top-level event_source is partner_app or installed_merchants:

{
  "webhook_event_id": "whev_1kmn0aExample",
  "event_type": "payment_intent.succeeded",
  "event_source": "installed_merchants",
  "payload_version": 2,
  "api_version": "2026-09-07",
  "partner_app_id": "papp_1kmn0aExample",
  "created_at": "2026-07-03T14:53:30Z",
  "test": false,
  "source": {
    "merchant_id": "mer_1kmn0aExample",
    "partner_app_install_id": "pinst_1kmn0aExample",
    "mode": "test",
    "environment_grant_id": "egrt_1kmn0aExample",
    "sandbox_id": "test_1kmn0aExample"
  },
  "data": {
    "object": {
      "payment_intent_id": "pi_1kmn0aExample",
      "status": "succeeded"
    }
  }
}

Unknown fields and event types#

Flint adds event types and resource fields over time, and an endpoint subscribed with ["*"] receives new types automatically. Ignore fields you don't recognize, and answer 2xx to event types you don't handle so Flint doesn't retry them.

Delivery status#

Each event gets one delivery per subscribed endpoint (wdel_...), and the status lives on the delivery, not the event:

Retry schedule#

A failed attempt retries on a fixed backoff, up to 9 automatic attempts in total:

Each delay is a minimum: Flint adds 0 to 20% at random, and a retry can start several seconds later still, longer when Flint is busy. The ninth attempt lands between about 71 and 86 hours after the first, plus that pickup time. Every attempt is signed fresh with a new timestamp, so a retry passes your timestamp check however late it runs.

Manual attempts don't use up the schedule:

• Resending a pending delivery attempts at once and leaves the schedule alone. A failed resend keeps the same next_retry_at, and a successful one marks the delivery delivered.
• Resending a failed or suppressed delivery makes one attempt. It becomes delivered if the attempt succeeds and failed if it doesn't; automatic retries don't restart.
• Creating a delivery with POST /v1/webhook-deliveries, for an event the endpoint has no delivery for, attempts at once. If that attempt fails, the delivery becomes pending and the automatic schedule starts.

Attempt numbers count every attempt, manual or automatic, so a resend between two retries takes the next number. Only automatic attempts count toward the 9, and automatic_attempt_count tracks them.

Inactive and deleted endpoints#

Setting an endpoint's status to inactive stops delivery to it immediately:

• In the same update, its pending deliveries become suppressed with suppression_reason endpoint_inactive, so Flint never sends them.
• Events that happen while it's inactive create no deliveries for it.
• Setting it back to active doesn't restart suppressed deliveries or backfill missed events. Resend the suppressed deliveries you need, and create deliveries for events that have none, while their payloads are retained. Or read current state from the API.

Deleting an endpoint suppresses its pending deliveries the same way, with suppression_reason endpoint_deleted. Its past deliveries keep their webhook_endpoint_id.

Delivery diagnostics#

Flint records why each attempt failed and why a delivery was suppressed. These calls return them:

A delivery that's three attempts into its schedule after your server answered 503:

curl https://api.withflintpay.com/v1/webhook-deliveries/wdel_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "webhook_delivery_id": "wdel_1kmn0aExample",
    "webhook_event_id": "whev_1kmn0aExample",
    "webhook_endpoint_id": "whep_1kmn0aExample",
    "status": "pending",
    "automatic_attempt_count": 3,
    "max_attempts": 9,
    "next_retry_at": "2026-07-03T15:07:12Z",
    "last_response_code": 503,
    "error_category": "webhook_http_5xx",
    "error_summary": "The webhook endpoint returned a server error.",
    "retryable": true,
    "recommended_action": "Inspect the endpoint logs for this delivery, fix the handler, then resend the webhook event.",
    "created_at": "2026-07-03T14:53:30Z",
    "updated_at": "2026-07-03T14:56:00Z"
  },
  "request_id": "req_01KWM638WGDX5RZ6THJCQBZCEV"
}

The Webhooks guide walks through debugging and recovering with these calls.

Resend and create refusals#

A resend while another attempt for the same delivery is running returns 409 OPERATION_IN_PROGRESS, with no reason. details[0] names the webhook_delivery and its ID. Wait for Retry-After: 5, then retry the same request with the same Idempotency-Key, as remediation.retry: same_request directs. The refusal isn't retained against the key.

Resending or creating a delivery after the event's 14-day payload retention returns 409 ACTION_NOT_ALLOWED with reason payload_expired and retry none. Read the resource with GET for its current state. Flint can't resend the expired event.

Creating a delivery for an endpoint that doesn't subscribe to the event returns 409 ACTION_NOT_ALLOWED with reason configuration_required. Add the event type to the endpoint's enabled_events; for partner endpoints, also check event_sources and installed_merchant_modes, then retry. An inactive endpoint returns ACTION_NOT_ALLOWED with reason unsupported_state; activate it first.

Failure fields#

Deliveries, attempts, and timeline attempts explain a failure with the same four fields:

On an attempt, these fields are present only when its status is failed. On a delivery, they describe the most recent failed attempt, and they're absent before any attempt and when the delivery is delivered or suppressed. A delivery also reports the latest HTTP status in last_response_code.

Attempts, including the one a resend or test event returns, also record your server's response:

The three response_ fields are returned only when your API key can read the resource the event is about, and response_headers and response_body_excerpt are removed after 14 days. Timeline attempts carry status_code, duration_milliseconds, and the failure fields, but not the response details.

Attempt status#

WebhookDeliveryAttempt.status, WebhookDeliveryAction.attempt_status, and webhook attempt timeline entries use the extensible message_attempt_status vocabulary. Webhooks emit these values:

Handle an unknown attempt status without failing to read the record. WebhookDelivery.status uses the closed message_status vocabulary and remains pending, delivered, failed, or suppressed. The delivery_status in action responses uses the same closed message_status vocabulary and the same values.

Failure categories#

Suppression reasons#

A suppressed delivery was stopped before Flint sent it. Flint checks each delivery again right before every attempt, so a delivery can be suppressed after earlier attempts failed. Suppressed deliveries have suppression_reason and no failure fields.

To deliver an event suppressed with endpoint_inactive, set the endpoint's status back to active and resend the delivery while the event's payload is retained.

Retention#

A delivery still pending when its event's payload expires stops retrying. It becomes failed with the failure fields of its last attempt, or suppressed with endpoint_inactive or endpoint_deleted if its endpoint is inactive or deleted.

Delivery order#

Events fan out independently, and a failed delivery retries while newer events keep flowing, so an older event can arrive after newer ones:

Treat a webhook as a signal that something changed, not as the change itself. When your logic needs current state, fetch the resource: GET /v1/subscriptions/{subscription_id} reflects everything that has happened to the subscription, whatever has reached your endpoint so far.

Don't order events by comparing timestamps. Two changes can share a second, and a retry can carry an older snapshot than one you already processed. If you mirror state locally, fetch the current resource on every event and write what the API returns.

Related#