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

Get webhook delivery#

GET/v1/webhook-deliveries/{webhook_delivery_id}Requires scope: webhooks.read or webhooks.write

Returns one endpoint delivery and its current retry state.

Path parameters
webhook_delivery_idstringrequired

Flint webhook delivery ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/webhook-deliveries/wdel_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "webhook_delivery_id": "wdel_123",
    "webhook_event_id": "whev_123",
    "webhook_endpoint_id": "whep_123",
    "status": "delivered",
    "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",
    "updated_at": "2026-03-17T14:30:02Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook delivery attempts#

GET/v1/webhook-deliveries/{webhook_delivery_id}/attemptsRequires scope: webhooks.read or webhooks.write

Returns the attempts recorded for a specific webhook delivery.

Path parameters
webhook_delivery_idstringrequired

Flint webhook delivery 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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/webhook-deliveries/wdel_123/attempts \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "webhook_delivery_attempt_id": "watt_123",
      "webhook_delivery_id": "wdel_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 delivery#

POST/v1/webhook-deliveries/{webhook_delivery_id}/resendIdempotentRequires scope: webhooks.write

Sends the canonical event payload again to the delivery's current webhook endpoint URL. Safe to retry with the same Idempotency-Key.

Path parameters
webhook_delivery_idstringrequired

Flint webhook delivery ID.

Request body
reasonstring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLEWEBHOOK_DELIVERY_IN_FLIGHTWEBHOOK_DELIVERY_UNAVAILABLEWEBHOOK_ENDPOINT_NOT_ACTIVEWEBHOOK_EVENT_PAYLOAD_EXPIRED
Bash
curl -X POST https://api.withflintpay.com/v1/webhook-deliveries/wdel_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_id": "wdel_123",
    "webhook_delivery_attempt_id": "watt_123",
    "delivery_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"
}

List webhook endpoints#

GET/v1/webhook-endpointsRequires scope: webhooks.read or webhooks.write

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
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.paid",
        "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-endpointsIdempotentRequires scope: webhooks.write

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
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.paid",
      "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.paid",
      "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}Requires scope: webhooks.read or webhooks.write

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
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.paid",
      "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}IdempotentRequires scope: webhooks.write

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
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.paid",
      "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}IdempotentRequires scope: webhooks.write

Deletes a webhook endpoint.

Path parameters
webhook_endpoint_idstringrequired

Flint webhook endpoint ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
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-secretIdempotentRequires scope: webhooks.write

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
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-eventsIdempotentRequires scope: webhooks.write

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.deletion_completedcustomer.deletion_rejectedcustomer.deletion_requestedcustomer.updateddispute.closeddispute.createddispute.lostdispute.needs_responsedispute.preventeddispute.updateddispute.warning_closeddispute.wonfraud_warning.createdfraud_warning.updateddelivery_rate_callback.archiveddelivery_rate_callback.createddelivery_rate_callback.deactivateddelivery_rate_callback.activateddelivery_rate_callback.updateddelivery_method.archiveddelivery_method.createddelivery_method.deactivateddelivery_method.activateddelivery_method.updateddelivery_location_set.archiveddelivery_location_set.createddelivery_location_set.deactivateddelivery_location_set.activateddelivery_location_set.updateddelivery_profile.archiveddelivery_profile.createddelivery_profile.deactivateddelivery_profile.activateddelivery_profile.updateddelivery_rate.archiveddelivery_rate.createddelivery_rate.updateddelivery_revocation.createddelivery_selection.committeddelivery_zone.archiveddelivery_zone.createddelivery_zone.deactivateddelivery_zone.activateddelivery_zone.updatedinvoice.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.reminder_dueinvoice.sentinvoice.updatedinvoice.voidedinventory.action_requiredinventory.level.updatedinventory.return_receipt.createdinventory.reservation.at_riskinventory.reservation.closedinventory.reservation.committedinventory.reservation.consumedinventory.reservation.createdinventory.reservation.hold_expiredinventory.reservation.releasedinventory.shortage.detectedmerchant_billing_balance.updatedmerchant.readiness.updatedmerchant_subscription_invoice.issuedmerchant_subscription_invoice.updatedorder.closedorder.createdorder.fulfillment.completedorder.fulfillment.createdorder.fulfillment.event.createdorder.fulfillment.package.createdorder.fulfillment.package.updatedorder.fulfillment.shipment.createdorder.fulfillment.shipment.updatedorder.fulfillment.status_changedorder.fulfillment.updatedorder.inventory_action_requiredorder.inventory_exception.createdorder.inventory_exception.resolvedorder.payment_authorization_expiredorder.payment_authorization_canceledorder.payment_authorizedorder.payment_capturedorder.partially_paidorder.paidorder.refundedorder.updatedpayment_intent.canceledpayment_intent.fulfillment_hold.updatedpayment_intent.payment_failedpayment_intent.processingpayment_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_settings.updatedrefund.createdrefund.failedrefund.updatedreport.failedreport.succeededreturn.canceledreturn.completedreturn.createdreturn.decision_recordedreturn.reopenedreturn.updatedreturn_disposition.createdreturn_disposition.updatedreturn_inspection.acceptance_decidedreturn_inspection.createdreturn_inspection.supersededreturn_receipt.createdreturn_receipt.supersededreturn_receipt.verifiedreturn_resolution.createdreturn_resolution.updatedreview.closedreview.openedsubscription.activatedsubscription.canceledsubscription.createdsubscription.past_duesubscription.pausedsubscription.payment_failedsubscription.payment_succeededsubscription.resumedsubscription.trial_ending
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
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_id": "wdel_123",
    "webhook_delivery_attempt_id": "watt_123",
    "delivery_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-typesRequires scope: webhooks.read or webhooks.write

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/webhook-event-types \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "event_type": "order.paid",
      "description": "An order became fully paid. Use order.payment_captured for each captured increment.",
      "event_sources": [
        "merchant",
        "installed_merchants"
      ]
    },
    {
      "event_type": "partner_app.install.created",
      "description": "A partner app install was created.",
      "event_sources": [
        "partner_app"
      ]
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook events#

GET/v1/webhook-eventsRequires scope: webhooks.read or webhooks.write

Returns recent canonical webhook 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 to events that have a delivery for this webhook endpoint.

delivery_statusenum

Filter to events that have a delivery with this status.

pendingdeliveredfailedsuppressed
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.deletion_completedcustomer.deletion_rejectedcustomer.deletion_requestedcustomer.updateddelivery_location_set.activateddelivery_location_set.archiveddelivery_location_set.createddelivery_location_set.deactivateddelivery_location_set.updateddelivery_method.activateddelivery_method.archiveddelivery_method.createddelivery_method.deactivateddelivery_method.updateddelivery_profile.activateddelivery_profile.archiveddelivery_profile.createddelivery_profile.deactivateddelivery_profile.updateddelivery_rate.archiveddelivery_rate.createddelivery_rate.updateddelivery_rate_callback.activateddelivery_rate_callback.archiveddelivery_rate_callback.createddelivery_rate_callback.deactivateddelivery_rate_callback.updateddelivery_revocation.createddelivery_selection.committeddelivery_zone.activateddelivery_zone.archiveddelivery_zone.createddelivery_zone.deactivateddelivery_zone.updateddispute.closeddispute.createddispute.lostdispute.needs_responsedispute.preventeddispute.updateddispute.warning_closeddispute.wonfraud_warning.createdfraud_warning.updatedinventory.action_requiredinventory.level.updatedinventory.reservation.at_riskinventory.reservation.closedinventory.reservation.committedinventory.reservation.consumedinventory.reservation.createdinventory.reservation.hold_expiredinventory.reservation.releasedinventory.return_receipt.createdinventory.shortage.detectedinvoice.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.reminder_dueinvoice.sentinvoice.updatedinvoice.voidedmerchant.readiness.updatedmerchant_billing_balance.updatedmerchant_subscription_invoice.issuedmerchant_subscription_invoice.updatedorder.closedorder.createdorder.fulfillment.completedorder.fulfillment.createdorder.fulfillment.event.createdorder.fulfillment.package.createdorder.fulfillment.package.updatedorder.fulfillment.shipment.createdorder.fulfillment.shipment.updatedorder.fulfillment.status_changedorder.fulfillment.updatedorder.inventory_action_requiredorder.inventory_exception.createdorder.inventory_exception.resolvedorder.paidorder.partially_paidorder.payment_authorization_canceledorder.payment_authorization_expiredorder.payment_authorizedorder.payment_capturedorder.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.fulfillment_hold.updatedpayment_intent.payment_failedpayment_intent.processingpayment_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_settings.updatedrefund.createdrefund.failedrefund.updatedreport.failedreport.succeededreturn.canceledreturn.completedreturn.createdreturn.decision_recordedreturn.reopenedreturn.updatedreturn_disposition.createdreturn_disposition.updatedreturn_inspection.acceptance_decidedreturn_inspection.createdreturn_inspection.supersededreturn_receipt.createdreturn_receipt.supersededreturn_receipt.verifiedreturn_resolution.createdreturn_resolution.updatedreview.closedreview.openedsubscription.activatedsubscription.canceledsubscription.createdsubscription.past_duesubscription.pausedsubscription.payment_failedsubscription.payment_succeededsubscription.resumedsubscription.trial_ending
resource_typeenum

Filter by affected resource type.

balancebalance_transactioncapabilitycheckout_sessioncustomerdisputefraud_warninginvoicemerchantinventory_countinventory_levelinventory_reallocationinventory_reservationinventory_reservation_lineinventory_return_receiptinventory_transferorderpayment_intentpayment_methodpayoutpayout_destinationpayout_settingsrefundreturnreturn_dispositionreturn_inspectionreturn_receiptreturn_resolutionreviewsubscription
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.

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/webhook-events \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "webhook_event_id": "whev_123",
      "event_source": "merchant",
      "event_type": "order.paid",
      "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",
      "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}Requires scope: webhooks.read or webhooks.write

Returns a specific webhook event for the authenticated merchant.

Path parameters
webhook_event_idstringrequired

Flint webhook event ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/webhook-events/whev_123 \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "webhook_event_id": "whev_123",
    "event_source": "merchant",
    "event_type": "order.paid",
    "payload": {
      "webhook_event_id": "whev_123",
      "event_type": "order.paid",
      "payload_version": 1,
      "mode": "live",
      "merchant_id": "mer_123",
      "created_at": "2026-03-17T14:30:00Z",
      "data": {
        "order_id": "ord_123",
        "status": "closed",
        "payment_status": "paid"
      }
    },
    "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",
    "created_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook deliveries#

GET/v1/webhook-events/{webhook_event_id}/deliveriesRequires scope: webhooks.read or webhooks.write

Returns endpoint deliveries created for one canonical 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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/webhook-events/whev_123/deliveries \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "webhook_delivery_id": "wdel_123",
      "webhook_event_id": "whev_123",
      "webhook_endpoint_id": "whep_123",
      "status": "delivered",
      "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",
      "updated_at": "2026-03-17T14:30:02Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Stream webhook events#

GET/v1/webhook-events/streamRequires scope: webhooks.read or webhooks.write

Streams canonical merchant webhook events created after the connection opens or after the supplied event ID. SSE event IDs are resumable webhook event IDs. Control records include ready, gap, withheld, and disconnect. Gap and withheld records advance the resumable cursor even when a resource payload is expired or hidden by API-key scope.

Query parameters
event_typeenum

Filter by canonical merchant webhook event type.

balance.updatedbalance_transaction.createdbalance_transaction.updatedcapability.updatedcheckout_session.closedcheckout_session.completedcheckout_session.expiredcheckout_session.invalidatedcustomer.createdcustomer.deletion_completedcustomer.deletion_rejectedcustomer.deletion_requestedcustomer.updateddelivery_location_set.activateddelivery_location_set.archiveddelivery_location_set.createddelivery_location_set.deactivateddelivery_location_set.updateddelivery_method.activateddelivery_method.archiveddelivery_method.createddelivery_method.deactivateddelivery_method.updateddelivery_profile.activateddelivery_profile.archiveddelivery_profile.createddelivery_profile.deactivateddelivery_profile.updateddelivery_rate.archiveddelivery_rate.createddelivery_rate.updateddelivery_rate_callback.activateddelivery_rate_callback.archiveddelivery_rate_callback.createddelivery_rate_callback.deactivateddelivery_rate_callback.updateddelivery_revocation.createddelivery_selection.committeddelivery_zone.activateddelivery_zone.archiveddelivery_zone.createddelivery_zone.deactivateddelivery_zone.updateddispute.closeddispute.createddispute.lostdispute.needs_responsedispute.preventeddispute.updateddispute.warning_closeddispute.wonfraud_warning.createdfraud_warning.updatedinventory.action_requiredinventory.level.updatedinventory.reservation.at_riskinventory.reservation.closedinventory.reservation.committedinventory.reservation.consumedinventory.reservation.createdinventory.reservation.hold_expiredinventory.reservation.releasedinventory.return_receipt.createdinventory.shortage.detectedinvoice.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.reminder_dueinvoice.sentinvoice.updatedinvoice.voidedmerchant.readiness.updatedmerchant_billing_balance.updatedmerchant_subscription_invoice.issuedmerchant_subscription_invoice.updatedorder.closedorder.createdorder.fulfillment.completedorder.fulfillment.createdorder.fulfillment.event.createdorder.fulfillment.package.createdorder.fulfillment.package.updatedorder.fulfillment.shipment.createdorder.fulfillment.shipment.updatedorder.fulfillment.status_changedorder.fulfillment.updatedorder.inventory_action_requiredorder.inventory_exception.createdorder.inventory_exception.resolvedorder.paidorder.partially_paidorder.payment_authorization_canceledorder.payment_authorization_expiredorder.payment_authorizedorder.payment_capturedorder.refundedorder.updatedpayment_intent.canceledpayment_intent.fulfillment_hold.updatedpayment_intent.payment_failedpayment_intent.processingpayment_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_settings.updatedrefund.createdrefund.failedrefund.updatedreport.failedreport.succeededreturn.canceledreturn.completedreturn.createdreturn.decision_recordedreturn.reopenedreturn.updatedreturn_disposition.createdreturn_disposition.updatedreturn_inspection.acceptance_decidedreturn_inspection.createdreturn_inspection.supersededreturn_receipt.createdreturn_receipt.supersededreturn_receipt.verifiedreturn_resolution.createdreturn_resolution.updatedreview.closedreview.openedsubscription.activatedsubscription.canceledsubscription.createdsubscription.past_duesubscription.pausedsubscription.payment_failedsubscription.payment_succeededsubscription.resumedsubscription.trial_ending
after_event_idstring

Webhook event ID to resume after. Last-Event-ID is preferred when reconnecting.

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLEWEBHOOK_STREAM_LIMITER_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/webhook-events/stream \
  -H "Authorization: Bearer YOUR_API_KEY"
Rate this doc