FlintflintDocs

Webhooks

Webhooks notify your systems when payments, orders, subscriptions, refunds, and invoices change. Use them as the durable trigger for fulfillment, entitlement updates, and downstream synchronization rather than polling.

Register an endpoint with an HTTPS URL and an optional enabled_events list (omit the list to receive everything). Flint delivers events as signed JSON POST requests with Standard Webhooks headers (webhook-id, webhook-timestamp, and webhook-signature), plus legacy X-Flint-* compatibility headers. Failed deliveries are retried on the documented backoff schedule. The signing secret is returned only at creation and rotation, and rotation keeps the previous secret valid for a 24-hour overlap so you can deploy without downtime. Beyond endpoint management, this surface lets you list delivered events, inspect per-attempt delivery history, send synthetic test events, and manually resend an event.

See the Webhooks guide for registration and signature verification examples, and the event catalog for event types and documented payload shapes.

Endpoints

List webhook endpoints#

GET/v1/webhook-endpoints

Returns a page of webhook endpoints for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

event_sourcesarray of enum

Filter by webhook endpoint event sources. Repeat or comma-separate to include multiple sources.

merchantpartner_appinstalled_merchants
partner_app_idstring

Filter by partner app ID for partner-source webhook endpoints.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/webhook-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "webhook_endpoint_id": "whep_123",
      "url": "https://example.com/webhooks/flint",
      "enabled_events": [
        "order.payment_captured",
        "order.payment_succeeded",
        "payment_intent.succeeded"
      ],
      "event_sources": [
        "merchant"
      ],
      "description": "Primary production endpoint",
      "enabled": true,
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create webhook endpoint#

POST/v1/webhook-endpointsIdempotent

Creates a webhook endpoint and returns the signing secret once.

Request body
descriptionstring
enabledboolean
enabled_eventsarray of string

Event types this endpoint receives. Empty means all merchant-owned events. For partner_app sources, empty defaults to all app lifecycle events. For installed_merchants sources, provide at least one installed-merchant event.

event_sourcesarray of enum

Event sources this endpoint receives. Defaults to merchant. Use partner_app for app lifecycle events and installed_merchants for events from merchants that installed the partner app.

merchantpartner_appinstalled_merchants
modeenum

Partner-source delivery mode. Valid values are test, live, and both. Mode applies to installed_merchants events; partner_app lifecycle events require both.

testliveboth
partner_app_idstring

Partner app that owns partner_app or installed_merchants event sources.

urlstringrequired
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "url": "https://example.com/webhooks/flint",
    "enabled_events": [
      "order.payment_captured",
      "order.payment_succeeded",
      "payment_intent.succeeded"
    ],
    "event_sources": [
      "merchant"
    ],
    "description": "Primary production endpoint",
    "enabled": true
  }'
JSON
{
  "data": {
    "webhook_endpoint_id": "whep_123",
    "url": "https://example.com/webhooks/flint",
    "secret": "whsec_123",
    "enabled_events": [
      "order.payment_captured",
      "order.payment_succeeded",
      "payment_intent.succeeded"
    ],
    "event_sources": [
      "merchant"
    ],
    "description": "Primary production endpoint",
    "enabled": true,
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get webhook endpoint#

GET/v1/webhook-endpoints/{webhook_endpoint_id}

Returns a single webhook endpoint by ID. The signing secret is omitted after creation.

Path parameters
webhook_endpoint_idstringrequired

Flint webhook endpoint ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/webhook-endpoints/whep_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "webhook_endpoint_id": "whep_123",
    "url": "https://example.com/webhooks/flint",
    "enabled_events": [
      "order.payment_captured",
      "order.payment_succeeded",
      "payment_intent.succeeded"
    ],
    "event_sources": [
      "merchant"
    ],
    "description": "Primary production endpoint",
    "enabled": true,
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update webhook endpoint#

PATCH/v1/webhook-endpoints/{webhook_endpoint_id}Idempotent

Updates the mutable fields on a webhook endpoint.

Path parameters
webhook_endpoint_idstringrequired

Flint webhook endpoint ID.

Request body
descriptionstring
enabledboolean
enabled_eventsarray of string

Event types this endpoint receives. Empty means all merchant-owned events. For partner_app sources, empty defaults to all app lifecycle events. For installed_merchants sources, provide at least one installed-merchant event.

event_sourcesarray of enum

Event sources this endpoint receives. Defaults to merchant. Use partner_app for app lifecycle events and installed_merchants for events from merchants that installed the partner app.

merchantpartner_appinstalled_merchants
modeenum

Partner-source delivery mode. Valid values are test, live, and both. Mode applies to installed_merchants events; partner_app lifecycle events require both.

testliveboth
partner_app_idstring

Partner app that owns partner_app or installed_merchants event sources.

urlstring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/webhook-endpoints/whep_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "description": "Updated production endpoint",
    "enabled": true
  }'
JSON
{
  "data": {
    "webhook_endpoint_id": "whep_123",
    "url": "https://example.com/webhooks/flint",
    "enabled_events": [
      "order.payment_captured",
      "order.payment_succeeded",
      "payment_intent.succeeded"
    ],
    "event_sources": [
      "merchant"
    ],
    "description": "Primary production endpoint",
    "enabled": true,
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Delete webhook endpoint#

DELETE/v1/webhook-endpoints/{webhook_endpoint_id}Idempotent

Deletes a webhook endpoint.

Path parameters
webhook_endpoint_idstringrequired

Flint webhook endpoint ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X DELETE https://api.withflintpay.com/v1/webhook-endpoints/whep_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "success": true
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Rotate webhook secret#

POST/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secretIdempotent

Rotates the signing secret for a webhook endpoint and returns the new secret once.

Path parameters
webhook_endpoint_idstringrequired

Flint webhook endpoint ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints/whep_123/rotate-secret \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "secret": "whsec_rotated_123"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create webhook test event#

POST/v1/webhook-endpoints/{webhook_endpoint_id}/test-eventsIdempotent

Creates and delivers a synthetic test webhook event to one active webhook endpoint. Safe to retry with the same Idempotency-Key.

Path parameters
webhook_endpoint_idstringrequired

Flint webhook endpoint ID.

Request body
event_typeenumrequired
balance.updatedbalance_transaction.createdbalance_transaction.updatedcapability.updatedcheckout_session.completedcheckout_session.closedcheckout_session.expiredcheckout_session.invalidatedcustomer.createdcustomer.updateddispute.closeddispute.createddispute.lostdispute.needs_responsedispute.preventeddispute.updateddispute.warning_closeddispute.woninvoice.collection_block_resolvedinvoice.collection_blockedinvoice.createdinvoice.delivery_failedinvoice.delivery_succeededinvoice.manual_payment_recordedinvoice.manual_payment_reversedinvoice.openedinvoice.paidinvoice.payment_attempt_canceledinvoice.payment_attempt_expiredinvoice.payment_failedinvoice.partially_paidinvoice.partially_refundedinvoice.refundedinvoice.sentinvoice.updatedinvoice.voidedmerchant.readiness.updatedorder.closedorder.createdorder.fulfillment.event.createdorder.fulfillment.package.createdorder.fulfillment.package.updatedorder.fulfillment.shipment.createdorder.fulfillment.shipment.updatedorder.fulfillment.status_changedorder.inventory_exception.createdorder.inventory_exception.resolvedorder.payment_authorization_expiredorder.payment_authorization_voidedorder.payment_authorizedorder.payment_capturedorder.payment_succeededorder.reconciliation_exception.createdorder.refundedorder.updatedpayment_intent.canceledpayment_intent.payment_failedpayment_intent.requires_actionpayment_intent.requires_capturepayment_intent.succeededpayment_method.failedpayment_method.removedpayment_method.savedpayout.canceledpayout.createdpayout.failedpayout.paidpayout.reversedpayout.updatedpayout_destination.createdpayout_destination.deletedpayout_destination.disabledpayout_destination.updatedpayout_destination_session.completedpayout_destination_session.updatedpayout_settings.updatedrefund.createdrefund.failedrefund.updatedsubscription.activatedsubscription.canceledsubscription.createdsubscription.past_duesubscription.pausedsubscription.payment_failedsubscription.payment_succeededsubscription.resumed
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints/whep_123/test-events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "event_type": "payment_intent.succeeded"
  }'
JSON
{
  "data": {
    "webhook_event_id": "whev_123",
    "webhook_delivery_attempt_id": "watt_123",
    "event_status": "delivered",
    "attempt_status": "delivered",
    "attempt_number": 1,
    "delivery_trigger": "test_event",
    "status_code": 200,
    "started_at": "2026-03-17T14:30:01Z",
    "completed_at": "2026-03-17T14:30:02Z",
    "duration_milliseconds": 982
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook event types#

GET/v1/webhook-event-types

Returns the webhook event types that can be used in enabled_events and event_type filters, grouped by the event source each type is valid for.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/webhook-event-types \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "event_type": "order.payment_succeeded",
      "event_sources": [
        "merchant",
        "installed_merchants"
      ]
    },
    {
      "event_type": "partner_app.install.created",
      "event_sources": [
        "partner_app"
      ]
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook events#

GET/v1/webhook-events

Returns recent webhook delivery events for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

webhook_endpoint_idstring

Filter by Flint webhook endpoint ID.

event_sourcearray of enum

Filter by webhook event source. Repeat or comma-separate to include multiple sources.

merchantpartner_appinstalled_merchants
partner_app_idstring

Filter by partner app ID for partner-source webhook events.

event_typeenum

Filter by webhook event type.

balance.updatedbalance_transaction.createdbalance_transaction.updatedcapability.updatedcheckout_session.closedcheckout_session.completedcheckout_session.expiredcheckout_session.invalidatedcustomer.createdcustomer.updateddispute.closeddispute.createddispute.lostdispute.needs_responsedispute.preventeddispute.updateddispute.warning_closeddispute.woninvoice.collection_block_resolvedinvoice.collection_blockedinvoice.createdinvoice.delivery_failedinvoice.delivery_succeededinvoice.manual_payment_recordedinvoice.manual_payment_reversedinvoice.openedinvoice.paidinvoice.partially_paidinvoice.partially_refundedinvoice.payment_attempt_canceledinvoice.payment_attempt_expiredinvoice.payment_failedinvoice.refundedinvoice.sentinvoice.updatedinvoice.voidedmerchant.readiness.updatedorder.closedorder.createdorder.fulfillment.event.createdorder.fulfillment.package.createdorder.fulfillment.package.updatedorder.fulfillment.shipment.createdorder.fulfillment.shipment.updatedorder.fulfillment.status_changedorder.inventory_exception.createdorder.inventory_exception.resolvedorder.payment_authorization_expiredorder.payment_authorization_voidedorder.payment_authorizedorder.payment_capturedorder.payment_succeededorder.reconciliation_exception.createdorder.refundedorder.updatedpartner_app.install.createdpartner_app.install.environment_grant.createdpartner_app.install.environment_grant.revokedpartner_app.install.permissions_updatedpartner_app.install.revokedpartner_app.install.updatedpayment_intent.canceledpayment_intent.payment_failedpayment_intent.requires_actionpayment_intent.requires_capturepayment_intent.succeededpayment_method.failedpayment_method.removedpayment_method.savedpayout.canceledpayout.createdpayout.failedpayout.paidpayout.reversedpayout.updatedpayout_destination.createdpayout_destination.deletedpayout_destination.disabledpayout_destination.updatedpayout_destination_session.completedpayout_destination_session.updatedpayout_settings.updatedrefund.createdrefund.failedrefund.updatedsubscription.activatedsubscription.canceledsubscription.createdsubscription.past_duesubscription.pausedsubscription.payment_failedsubscription.payment_succeededsubscription.resumed
statusenum

Filter by delivery status.

pendingdeliveredfailed
resource_typeenum

Filter by affected resource type.

balancebalance_transactioncapabilitycheckout_sessioncustomerdisputeinvoiceorderpayment_intentpayment_methodpayoutpayout_destinationpayout_destination_sessionpayout_settingsrefundsubscription
resource_idstring

Filter by affected resource ID.

api_request_log_idstring

Filter by API request log ID associated with the event.

request_idstring

Filter by request ID associated with the event.

correlation_idstring

Filter by correlation ID associated with the event.

diagnostic_categoryenum

Filter by delivery attempt diagnostic category.

timeoutdns_errortls_errorconnection_errorblocked_targetrequest_errorhttp_error
created_afterstring

RFC3339 lower bound for webhook event created_at.

created_beforestring

RFC3339 upper bound for webhook event created_at.

includearray of enum

Optional comma-separated expansions. Use test_events to include synthetic webhook test events.

test_events
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/webhook-events \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "webhook_event_id": "whev_123",
      "webhook_endpoint_id": "whep_123",
      "event_type": "order.payment_succeeded",
      "status": "delivered",
      "event_origin": "business_event",
      "test": false,
      "resource_type": "order",
      "resource_id": "ord_123",
      "api_request_log_id": "rlog_123",
      "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
      "correlation_id": "rlog_123",
      "automatic_attempt_count": 1,
      "max_attempts": 9,
      "last_response_code": 200,
      "delivered_at": "2026-03-17T14:30:02Z",
      "created_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get webhook event#

GET/v1/webhook-events/{webhook_event_id}

Returns a specific webhook event for the authenticated merchant.

Path parameters
webhook_event_idstringrequired

Flint webhook event ID.

Query parameters
expandarray of enum

Supported expansions: webhook_endpoint. Expansion requires webhooks.webhooks.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=webhook_endpoint&expand=webhook_endpoint. Comma-separated values, expand[]=webhook_endpoint, and numeric expand[0]=webhook_endpoint are accepted for common client compatibility.

webhook_endpoint
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/webhook-events/whev_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

List webhook delivery attempts#

GET/v1/webhook-events/{webhook_event_id}/delivery-attempts

Returns the delivery attempts recorded for a specific webhook event.

Path parameters
webhook_event_idstringrequired

Flint webhook event ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/webhook-events/whev_123/delivery-attempts \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "webhook_delivery_attempt_id": "watt_123",
      "webhook_event_id": "whev_123",
      "attempt_number": 1,
      "delivery_trigger": "automatic_delivery",
      "status": "failed",
      "status_code": 502,
      "error_message": "HTTP 502",
      "response_headers": "{\"Content-Type\":\"application/json\",\"X-Api-Token\":\"[REDACTED]\"}",
      "response_body_excerpt": "{\"error\":\"bad gateway\",\"api_token\":\"[REDACTED]\"}",
      "response_content_type": "application/json",
      "diagnostic_category": "http_error",
      "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.",
      "started_at": "2026-03-17T14:30:01Z",
      "completed_at": "2026-03-17T14:30:02Z",
      "duration_milliseconds": 982
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Resend webhook event#

POST/v1/webhook-events/{webhook_event_id}/resendIdempotent

Manually sends the existing webhook event payload again to the current webhook endpoint URL. Safe to retry with the same Idempotency-Key.

Path parameters
webhook_event_idstringrequired

Flint webhook event ID.

Request body
reasonstring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/webhook-events/whev_123/resend \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "reason": "Endpoint was fixed after returning 500s."
  }'
JSON
{
  "data": {
    "webhook_event_id": "whev_123",
    "webhook_delivery_attempt_id": "watt_123",
    "event_status": "delivered",
    "attempt_status": "delivered",
    "attempt_number": 1,
    "delivery_trigger": "manual_resend",
    "status_code": 200,
    "started_at": "2026-03-17T14:30:01Z",
    "completed_at": "2026-03-17T14:30:02Z",
    "duration_milliseconds": 982
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc