flintDocs

Webhooks

Flint sends signed webhook events when payments, orders, subscriptions, refunds, and invoices change, following the Standard Webhooks specification. 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.

Note:

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

Include an optional reason_message when resending a webhook delivery to record your note. The delivery action and its attempt echo the note as reason_message.

The Webhook object#

Every field on a webhook, as returned by retrieve and carried by the endpoints below.

Attributes

automatic_attempt_countintegerRequired
created_atstringRequired

RFC3339 timestamp.

delivered_atstring

RFC3339 timestamp.

error_categoryenum
  • authentication
  • authorization
  • validation
  • server_error
  • rate_limit
  • idempotency
  • merchant_readiness
  • payment
  • request_error
  • webhook_timeout
  • webhook_dns
  • webhook_tls
  • webhook_connection
  • webhook_blocked_target
  • webhook_request
  • webhook_http_5xx
  • webhook_http_4xx
  • webhook_delivery
error_summarystring
last_errorstring
last_response_codeinteger
max_attemptsintegerRequired
next_retry_atstring

RFC3339 timestamp.

recommended_actionstring
reference_urlstring
retryableboolean
statusenumRequired
  • pending
  • delivered
  • failed
  • suppressed
updated_atstringRequired

RFC3339 timestamp.

webhook_delivery_idstringRequired
webhook_endpoint_idstringRequired
webhook_event_idstringRequired
JSON
{
  "automatic_attempt_count": 1,
  "created_at": "2026-03-17T14:30:00Z",
  "delivered_at": "2026-03-17T14:30:02Z",
  "last_response_code": 200,
  "max_attempts": 9,
  "status": "delivered",
  "updated_at": "2026-03-17T14:30:02Z",
  "webhook_delivery_id": "wdel_123",
  "webhook_endpoint_id": "whep_123",
  "webhook_event_id": "whev_123"
}

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
curl https://api.withflintpay.com/v1/webhook-deliveries/wdel_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "automatic_attempt_count": 1,
    "created_at": "2026-03-17T14:30:00Z",
    "delivered_at": "2026-03-17T14:30:02Z",
    "last_response_code": 200,
    "max_attempts": 9,
    "status": "delivered",
    "updated_at": "2026-03-17T14:30:02Z",
    "webhook_delivery_id": "wdel_123",
    "webhook_endpoint_id": "whep_123",
    "webhook_event_id": "whev_123"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook delivery attempts#

GET/v1/webhook-deliveries/{webhook_delivery_id}/attempts

Requires 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
curl https://api.withflintpay.com/v1/webhook-deliveries/wdel_123/attempts \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "api_version": "2026-09-07",
      "attempt_number": 1,
      "completed_at": "2026-03-17T14:30:02Z",
      "delivery_trigger": "automatic_delivery",
      "diagnostic_category": "http_error",
      "duration_milliseconds": 982,
      "error_category": "webhook_http_5xx",
      "error_message": "HTTP 502",
      "error_summary": "The webhook endpoint returned a server error.",
      "recommended_action": "Inspect the endpoint logs for this delivery, fix the handler, then resend the webhook event.",
      "response_body_excerpt": "{\"error\":\"bad gateway\",\"api_token\":\"[REDACTED]\"}",
      "response_content_type": "application/json",
      "response_headers": "{\"Content-Type\":\"application/json\",\"X-Api-Token\":\"[REDACTED]\"}",
      "retryable": true,
      "started_at": "2026-03-17T14:30:01Z",
      "status": "failed",
      "status_code": 502,
      "webhook_delivery_attempt_id": "watt_123",
      "webhook_delivery_id": "wdel_123",
      "webhook_event_id": "whev_123"
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Resend webhook delivery#

POST/v1/webhook-deliveries/{webhook_delivery_id}/resendIdempotent

Requires 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

reason_messagestring

Your note explaining this action.

Response · 200

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/webhook-deliveries/wdel_123/resend \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "reason_message": "Endpoint was fixed after returning 500s."
  }'

List webhook endpoints#

GET/v1/webhook-endpoints

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

  • merchant
  • partner_app
  • installed_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
curl https://api.withflintpay.com/v1/webhook-endpoints \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "api_version": "2026-09-07",
      "created_at": "2026-03-17T14:30:00Z",
      "description": "Primary production endpoint",
      "enabled": true,
      "enabled_events": [
        "order.payment_captured",
        "order.paid",
        "payment_intent.succeeded"
      ],
      "event_sources": [
        "merchant"
      ],
      "updated_at": "2026-03-17T14:30:00Z",
      "url": "https://example.com/webhooks/flint",
      "webhook_endpoint_id": "whep_123"
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create webhook endpoint#

POST/v1/webhook-endpointsIdempotent

Requires scope webhooks.write

Creates a webhook endpoint and returns the signing secret once.

Request body

api_versionstring

Set default to follow the merchant default, or a supported YYYY-MM-DD version to pin this endpoint. Omission follows the merchant default. Null is not accepted.

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.

  • merchant
  • partner_app
  • installed_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.

  • test
  • live
  • both
partner_app_idstring

Partner app that owns partner_app or installed_merchants event sources.

urlstringRequired

Response · 201

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "description": "Primary production endpoint",
    "enabled": true,
    "enabled_events": [
      "order.payment_captured",
      "order.paid",
      "payment_intent.succeeded"
    ],
    "event_sources": [
      "merchant"
    ],
    "url": "https://example.com/webhooks/flint"
  }'

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

Same response as Create webhook endpoint.

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

Update webhook endpoint#

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

Requires scope webhooks.write

Updates the mutable fields on a webhook endpoint.

Path parameters

webhook_endpoint_idstringRequired

Flint webhook endpoint ID.

Request body

api_versionstring

Set default to follow the merchant default, or a supported YYYY-MM-DD version to pin this endpoint. Omit to leave unchanged. Null is not accepted. Switching between a pin and default clears the rollback offer.

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.

  • merchant
  • partner_app
  • installed_merchants
expected_api_versionstring

Apply api_version only if this matches the resource's current api_version. A mismatch returns HTTP 409. Requires api_version; null is not accepted.

modeenum

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

  • test
  • live
  • both
partner_app_idstring

Partner app that owns partner_app or installed_merchants event sources.

urlstring

Response · 200

Same response as Create webhook endpoint.

curl -X PATCH https://api.withflintpay.com/v1/webhook-endpoints/whep_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "description": "Updated production endpoint",
    "enabled": true
  }'

Delete webhook endpoint#

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

Requires scope webhooks.write

Marks a webhook endpoint as deleted so it no longer receives events.

Path parameters

webhook_endpoint_idstringRequired

Flint webhook endpoint ID.

Response · 200

dataobjectRequired
metaobject
request_idstring
curl -X DELETE https://api.withflintpay.com/v1/webhook-endpoints/whep_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rotate webhook secret#

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

Requires 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
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints/whep_123/rotate-secret \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create webhook test event#

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

Requires 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.updated
  • balance_transaction.created
  • balance_transaction.updated
  • capability.updated
  • checkout_session.completed
  • checkout_session.closed
  • checkout_session.expired
  • checkout_session.invalidated
  • credit_note.allocation_created
  • credit_note.allocation_reversed
  • credit_note.created
  • credit_note.issued
  • credit_note.updated
  • credit_note.voided
  • customer.created
  • customer.deletion_completed
  • customer.deletion_rejected
  • customer.deletion_requested
  • customer.updated
  • custom_domain.status_changed
  • dispute.closed
  • dispute.created
  • dispute.lost
  • dispute.needs_response
  • dispute.prevented
  • dispute.updated
  • dispute.warning_closed
  • dispute.won
  • fraud_warning.created
  • fraud_warning.updated
  • gift_card.created
  • gift_card.updated
  • gift_card_load.created
  • gift_card_load.updated
  • gift_card_notification.created
  • gift_card_notification.updated
  • gift_card_redemption.created
  • gift_card_redemption.updated
  • gift_card_transaction.created
  • delivery_rate_callback.archived
  • delivery_rate_callback.created
  • delivery_rate_callback.deactivated
  • delivery_rate_callback.activated
  • delivery_rate_callback.updated
  • delivery_method.archived
  • delivery_method.created
  • delivery_method.deactivated
  • delivery_method.activated
  • delivery_method.updated
  • delivery_location_set.archived
  • delivery_location_set.created
  • delivery_location_set.deactivated
  • delivery_location_set.activated
  • delivery_location_set.updated
  • delivery_profile.archived
  • delivery_profile.created
  • delivery_profile.deactivated
  • delivery_profile.activated
  • delivery_profile.updated
  • delivery_rate.archived
  • delivery_rate.created
  • delivery_rate.updated
  • delivery_revocation.created
  • delivery_selection.committed
  • delivery_zone.archived
  • delivery_zone.created
  • delivery_zone.deactivated
  • delivery_zone.activated
  • delivery_zone.updated
  • invoice.collection_block_resolved
  • invoice.collection_blocked
  • invoice.credited
  • invoice.created
  • invoice.delivery_failed
  • invoice.delivery_succeeded
  • invoice.issued
  • invoice.issue_failed
  • invoice.late_fee_due
  • invoice.late_fee_assessed
  • invoice.late_fee_waived
  • invoice.marked_uncollectible
  • invoice.manual_payment_recorded
  • invoice.manual_payment_reversed
  • invoice.overdue
  • invoice.paid
  • invoice.payment_processing
  • invoice.payment_attempt_canceled
  • invoice.payment_attempt_expired
  • invoice.payment_failed
  • invoice.partially_paid
  • invoice.partially_refunded
  • invoice.refunded
  • invoice.reminder_due
  • invoice.sent
  • invoice.updated
  • invoice.voided
  • inventory.action_required
  • inventory.count.applied
  • inventory.level.updated
  • inventory.receipt.created
  • inventory.reservation.at_risk
  • inventory.reservation.closed
  • inventory.reservation.committed
  • inventory.reservation.consumed
  • inventory.reservation.created
  • inventory.reservation.hold_expired
  • inventory.reservation.released
  • inventory.shortage.detected
  • inventory.transfer.closed
  • inventory.transfer.departed
  • inventory.transfer.lost
  • inventory.transfer.received
  • inventory.transfer.returned
  • merchant_billing_balance.updated
  • merchant.readiness.updated
  • merchant_subscription_invoice.issued
  • merchant_subscription_invoice.updated
  • order.closed
  • order.created
  • order.fulfillment.completed
  • order.fulfillment.created
  • order.fulfillment.event.created
  • order.fulfillment.package.created
  • order.fulfillment.package.updated
  • order.fulfillment.shipment.created
  • order.fulfillment.shipment.updated
  • order.fulfillment.status_changed
  • order.fulfillment.updated
  • order.inventory_action_required
  • order.inventory_exception.created
  • order.inventory_exception.resolved
  • order.payment_authorization_expired
  • order.payment_authorization_canceled
  • order.payment_authorized
  • order.payment_captured
  • order.partially_paid
  • order.paid
  • order.refunded
  • order.updated
  • payment_intent.canceled
  • payment_intent.fulfillment_hold.updated
  • payment_intent.payment_failed
  • payment_intent.processing
  • payment_intent.requires_action
  • payment_intent.requires_capture
  • payment_intent.succeeded
  • payment_method.failed
  • payment_method.removed
  • payment_method.saved
  • payout.canceled
  • payout.created
  • payout.failed
  • payout.paid
  • payout.reversed
  • payout.updated
  • payout_destination.created
  • payout_destination.deleted
  • payout_destination.disabled
  • payout_destination.updated
  • payout_settings.updated
  • refund.created
  • refund.failed
  • refund.updated
  • report.failed
  • report.succeeded
  • return.canceled
  • return.completed
  • return.created
  • return.decision_recorded
  • return.reopened
  • return.updated
  • return_disposition.created
  • return_disposition.updated
  • return_inspection.acceptance_decided
  • return_inspection.created
  • return_inspection.superseded
  • return_receipt.created
  • return_receipt.superseded
  • return_receipt.verified
  • return_resolution.created
  • return_resolution.updated
  • review.closed
  • review.opened
  • subscription.activated
  • subscription.canceled
  • subscription.cancellation_scheduled
  • subscription.created
  • subscription.dunning_exhausted
  • subscription.past_due
  • subscription.paused
  • subscription.payment_failed
  • subscription.payment_succeeded
  • subscription_payment_retry.created
  • subscription_payment_retry.succeeded
  • subscription_payment_retry.failed
  • subscription.reactivated
  • subscription.resumed
  • subscription.renewal_upcoming
  • subscription.trial_ending
  • subscription.updated
  • subscription.delivery_action_required
  • subscription.delivery_pause_upcoming
  • subscription.delivery_updated
  • subscription.cycle_skipped
  • subscription_delivery_migration.completed

Response · 201

Same response as Resend webhook delivery.

curl -X POST https://api.withflintpay.com/v1/webhook-endpoints/whep_123/test-events \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "event_type": "payment_intent.succeeded"
  }'

List webhook event types#

GET/v1/webhook-event-types

Requires 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
curl https://api.withflintpay.com/v1/webhook-event-types \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "description": "An order became fully paid. Use order.payment_captured for each captured increment.",
      "event_sources": [
        "merchant",
        "installed_merchants"
      ],
      "event_type": "order.paid"
    },
    {
      "description": "A partner app install was created.",
      "event_sources": [
        "partner_app"
      ],
      "event_type": "partner_app.install.created"
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook events#

GET/v1/webhook-events

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

  • pending
  • delivered
  • failed
  • suppressed
event_sourcearray of enum

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

  • merchant
  • partner_app
  • installed_merchants
partner_app_idstring

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

event_typeenum

Filter by webhook event type.

  • balance.updated
  • balance_transaction.created
  • balance_transaction.updated
  • capability.updated
  • checkout_session.closed
  • checkout_session.completed
  • checkout_session.expired
  • checkout_session.invalidated
  • credit_note.allocation_created
  • credit_note.allocation_reversed
  • credit_note.created
  • credit_note.issued
  • credit_note.updated
  • credit_note.voided
  • custom_domain.status_changed
  • customer.created
  • customer.deletion_completed
  • customer.deletion_rejected
  • customer.deletion_requested
  • customer.updated
  • delivery_location_set.activated
  • delivery_location_set.archived
  • delivery_location_set.created
  • delivery_location_set.deactivated
  • delivery_location_set.updated
  • delivery_method.activated
  • delivery_method.archived
  • delivery_method.created
  • delivery_method.deactivated
  • delivery_method.updated
  • delivery_profile.activated
  • delivery_profile.archived
  • delivery_profile.created
  • delivery_profile.deactivated
  • delivery_profile.updated
  • delivery_rate.archived
  • delivery_rate.created
  • delivery_rate.updated
  • delivery_rate_callback.activated
  • delivery_rate_callback.archived
  • delivery_rate_callback.created
  • delivery_rate_callback.deactivated
  • delivery_rate_callback.updated
  • delivery_revocation.created
  • delivery_selection.committed
  • delivery_zone.activated
  • delivery_zone.archived
  • delivery_zone.created
  • delivery_zone.deactivated
  • delivery_zone.updated
  • dispute.closed
  • dispute.created
  • dispute.lost
  • dispute.needs_response
  • dispute.prevented
  • dispute.updated
  • dispute.warning_closed
  • dispute.won
  • fraud_warning.created
  • fraud_warning.updated
  • gift_card.created
  • gift_card.updated
  • gift_card_load.created
  • gift_card_load.updated
  • gift_card_notification.created
  • gift_card_notification.updated
  • gift_card_redemption.created
  • gift_card_redemption.updated
  • gift_card_transaction.created
  • inventory.action_required
  • inventory.count.applied
  • inventory.level.updated
  • inventory.receipt.created
  • inventory.reservation.at_risk
  • inventory.reservation.closed
  • inventory.reservation.committed
  • inventory.reservation.consumed
  • inventory.reservation.created
  • inventory.reservation.hold_expired
  • inventory.reservation.released
  • inventory.shortage.detected
  • inventory.transfer.closed
  • inventory.transfer.departed
  • inventory.transfer.lost
  • inventory.transfer.received
  • inventory.transfer.returned
  • invoice.collection_block_resolved
  • invoice.collection_blocked
  • invoice.created
  • invoice.credited
  • invoice.delivery_failed
  • invoice.delivery_succeeded
  • invoice.issue_failed
  • invoice.issued
  • invoice.late_fee_assessed
  • invoice.late_fee_due
  • invoice.late_fee_waived
  • invoice.manual_payment_recorded
  • invoice.manual_payment_reversed
  • invoice.marked_uncollectible
  • invoice.overdue
  • invoice.paid
  • invoice.partially_paid
  • invoice.partially_refunded
  • invoice.payment_attempt_canceled
  • invoice.payment_attempt_expired
  • invoice.payment_failed
  • invoice.payment_processing
  • invoice.refunded
  • invoice.reminder_due
  • invoice.sent
  • invoice.updated
  • invoice.voided
  • merchant.readiness.updated
  • merchant_billing_balance.updated
  • merchant_subscription_invoice.issued
  • merchant_subscription_invoice.updated
  • order.closed
  • order.created
  • order.fulfillment.completed
  • order.fulfillment.created
  • order.fulfillment.event.created
  • order.fulfillment.package.created
  • order.fulfillment.package.updated
  • order.fulfillment.shipment.created
  • order.fulfillment.shipment.updated
  • order.fulfillment.status_changed
  • order.fulfillment.updated
  • order.inventory_action_required
  • order.inventory_exception.created
  • order.inventory_exception.resolved
  • order.paid
  • order.partially_paid
  • order.payment_authorization_canceled
  • order.payment_authorization_expired
  • order.payment_authorized
  • order.payment_captured
  • order.refunded
  • order.updated
  • partner_app.install.created
  • partner_app.install.environment_grant.created
  • partner_app.install.environment_grant.revoked
  • partner_app.install.permissions_updated
  • partner_app.install.revoked
  • partner_app.install.updated
  • payment_intent.canceled
  • payment_intent.fulfillment_hold.updated
  • payment_intent.payment_failed
  • payment_intent.processing
  • payment_intent.requires_action
  • payment_intent.requires_capture
  • payment_intent.succeeded
  • payment_method.failed
  • payment_method.removed
  • payment_method.saved
  • payout.canceled
  • payout.created
  • payout.failed
  • payout.paid
  • payout.reversed
  • payout.updated
  • payout_destination.created
  • payout_destination.deleted
  • payout_destination.disabled
  • payout_destination.updated
  • payout_settings.updated
  • refund.created
  • refund.failed
  • refund.updated
  • report.failed
  • report.succeeded
  • return.canceled
  • return.completed
  • return.created
  • return.decision_recorded
  • return.reopened
  • return.updated
  • return_disposition.created
  • return_disposition.updated
  • return_inspection.acceptance_decided
  • return_inspection.created
  • return_inspection.superseded
  • return_receipt.created
  • return_receipt.superseded
  • return_receipt.verified
  • return_resolution.created
  • return_resolution.updated
  • review.closed
  • review.opened
  • subscription.activated
  • subscription.canceled
  • subscription.cancellation_scheduled
  • subscription.created
  • subscription.cycle_skipped
  • subscription.delivery_action_required
  • subscription.delivery_pause_upcoming
  • subscription.delivery_updated
  • subscription.dunning_exhausted
  • subscription.past_due
  • subscription.paused
  • subscription.payment_failed
  • subscription.payment_succeeded
  • subscription.reactivated
  • subscription.renewal_upcoming
  • subscription.resumed
  • subscription.trial_ending
  • subscription.updated
  • subscription_delivery_migration.completed
  • subscription_payment_retry.created
  • subscription_payment_retry.failed
  • subscription_payment_retry.succeeded
resource_typeenum

Filter by affected resource type.

  • balance
  • balance_transaction
  • capability
  • checkout_session
  • customer
  • dispute
  • fraud_warning
  • invoice
  • merchant
  • inventory_count
  • inventory_level
  • inventory_reservation
  • inventory_reservation_line
  • inventory_receipt
  • inventory_transfer
  • order
  • payment_intent
  • payment_method
  • payout
  • payout_destination
  • payout_settings
  • refund
  • return
  • return_disposition
  • return_inspection
  • return_receipt
  • return_resolution
  • review
  • subscription
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
curl https://api.withflintpay.com/v1/webhook-events \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "api_request_log_id": "rlog_123",
      "correlation_id": "rlog_123",
      "created_at": "2026-03-17T14:30:00Z",
      "event_origin": "business_event",
      "event_source": "merchant",
      "event_type": "order.paid",
      "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
      "resource_id": "ord_123",
      "resource_type": "order",
      "test": false,
      "webhook_event_id": "whev_123"
    }
  ],
  "next_page_token": "example",
  "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
curl https://api.withflintpay.com/v1/webhook-events/whev_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "api_request_log_id": "rlog_123",
    "correlation_id": "rlog_123",
    "created_at": "2026-03-17T14:30:00Z",
    "event_origin": "business_event",
    "event_source": "merchant",
    "event_type": "order.paid",
    "payload": {
      "api_version": "2026-02-01",
      "created_at": "2026-03-17T14:30:00Z",
      "data": {
        "order_id": "ord_123",
        "payment_status": "paid",
        "status": "closed"
      },
      "event_type": "order.paid",
      "merchant_id": "mer_123",
      "mode": "live",
      "payload_version": 1,
      "webhook_event_id": "whev_123"
    },
    "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
    "resource_id": "ord_123",
    "resource_type": "order",
    "test": false,
    "webhook_event_id": "whev_123"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List webhook deliveries#

GET/v1/webhook-events/{webhook_event_id}/deliveries

Requires 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
curl https://api.withflintpay.com/v1/webhook-events/whev_123/deliveries \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "automatic_attempt_count": 1,
      "created_at": "2026-03-17T14:30:00Z",
      "delivered_at": "2026-03-17T14:30:02Z",
      "last_response_code": 200,
      "max_attempts": 9,
      "status": "delivered",
      "updated_at": "2026-03-17T14:30:02Z",
      "webhook_delivery_id": "wdel_123",
      "webhook_endpoint_id": "whep_123",
      "webhook_event_id": "whev_123"
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Stream webhook events#

GET/v1/webhook-events/stream

Requires 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.updated
  • balance_transaction.created
  • balance_transaction.updated
  • capability.updated
  • checkout_session.closed
  • checkout_session.completed
  • checkout_session.expired
  • checkout_session.invalidated
  • credit_note.allocation_created
  • credit_note.allocation_reversed
  • credit_note.created
  • credit_note.issued
  • credit_note.updated
  • credit_note.voided
  • custom_domain.status_changed
  • customer.created
  • customer.deletion_completed
  • customer.deletion_rejected
  • customer.deletion_requested
  • customer.updated
  • delivery_location_set.activated
  • delivery_location_set.archived
  • delivery_location_set.created
  • delivery_location_set.deactivated
  • delivery_location_set.updated
  • delivery_method.activated
  • delivery_method.archived
  • delivery_method.created
  • delivery_method.deactivated
  • delivery_method.updated
  • delivery_profile.activated
  • delivery_profile.archived
  • delivery_profile.created
  • delivery_profile.deactivated
  • delivery_profile.updated
  • delivery_rate.archived
  • delivery_rate.created
  • delivery_rate.updated
  • delivery_rate_callback.activated
  • delivery_rate_callback.archived
  • delivery_rate_callback.created
  • delivery_rate_callback.deactivated
  • delivery_rate_callback.updated
  • delivery_revocation.created
  • delivery_selection.committed
  • delivery_zone.activated
  • delivery_zone.archived
  • delivery_zone.created
  • delivery_zone.deactivated
  • delivery_zone.updated
  • dispute.closed
  • dispute.created
  • dispute.lost
  • dispute.needs_response
  • dispute.prevented
  • dispute.updated
  • dispute.warning_closed
  • dispute.won
  • fraud_warning.created
  • fraud_warning.updated
  • gift_card.created
  • gift_card.updated
  • gift_card_load.created
  • gift_card_load.updated
  • gift_card_notification.created
  • gift_card_notification.updated
  • gift_card_redemption.created
  • gift_card_redemption.updated
  • gift_card_transaction.created
  • inventory.action_required
  • inventory.count.applied
  • inventory.level.updated
  • inventory.receipt.created
  • inventory.reservation.at_risk
  • inventory.reservation.closed
  • inventory.reservation.committed
  • inventory.reservation.consumed
  • inventory.reservation.created
  • inventory.reservation.hold_expired
  • inventory.reservation.released
  • inventory.shortage.detected
  • inventory.transfer.closed
  • inventory.transfer.departed
  • inventory.transfer.lost
  • inventory.transfer.received
  • inventory.transfer.returned
  • invoice.collection_block_resolved
  • invoice.collection_blocked
  • invoice.created
  • invoice.credited
  • invoice.delivery_failed
  • invoice.delivery_succeeded
  • invoice.issue_failed
  • invoice.issued
  • invoice.late_fee_assessed
  • invoice.late_fee_due
  • invoice.late_fee_waived
  • invoice.manual_payment_recorded
  • invoice.manual_payment_reversed
  • invoice.marked_uncollectible
  • invoice.overdue
  • invoice.paid
  • invoice.partially_paid
  • invoice.partially_refunded
  • invoice.payment_attempt_canceled
  • invoice.payment_attempt_expired
  • invoice.payment_failed
  • invoice.payment_processing
  • invoice.refunded
  • invoice.reminder_due
  • invoice.sent
  • invoice.updated
  • invoice.voided
  • merchant.readiness.updated
  • merchant_billing_balance.updated
  • merchant_subscription_invoice.issued
  • merchant_subscription_invoice.updated
  • order.closed
  • order.created
  • order.fulfillment.completed
  • order.fulfillment.created
  • order.fulfillment.event.created
  • order.fulfillment.package.created
  • order.fulfillment.package.updated
  • order.fulfillment.shipment.created
  • order.fulfillment.shipment.updated
  • order.fulfillment.status_changed
  • order.fulfillment.updated
  • order.inventory_action_required
  • order.inventory_exception.created
  • order.inventory_exception.resolved
  • order.paid
  • order.partially_paid
  • order.payment_authorization_canceled
  • order.payment_authorization_expired
  • order.payment_authorized
  • order.payment_captured
  • order.refunded
  • order.updated
  • payment_intent.canceled
  • payment_intent.fulfillment_hold.updated
  • payment_intent.payment_failed
  • payment_intent.processing
  • payment_intent.requires_action
  • payment_intent.requires_capture
  • payment_intent.succeeded
  • payment_method.failed
  • payment_method.removed
  • payment_method.saved
  • payout.canceled
  • payout.created
  • payout.failed
  • payout.paid
  • payout.reversed
  • payout.updated
  • payout_destination.created
  • payout_destination.deleted
  • payout_destination.disabled
  • payout_destination.updated
  • payout_settings.updated
  • refund.created
  • refund.failed
  • refund.updated
  • report.failed
  • report.succeeded
  • return.canceled
  • return.completed
  • return.created
  • return.decision_recorded
  • return.reopened
  • return.updated
  • return_disposition.created
  • return_disposition.updated
  • return_inspection.acceptance_decided
  • return_inspection.created
  • return_inspection.superseded
  • return_receipt.created
  • return_receipt.superseded
  • return_receipt.verified
  • return_resolution.created
  • return_resolution.updated
  • review.closed
  • review.opened
  • subscription.activated
  • subscription.canceled
  • subscription.cancellation_scheduled
  • subscription.created
  • subscription.cycle_skipped
  • subscription.delivery_action_required
  • subscription.delivery_pause_upcoming
  • subscription.delivery_updated
  • subscription.dunning_exhausted
  • subscription.past_due
  • subscription.paused
  • subscription.payment_failed
  • subscription.payment_succeeded
  • subscription.reactivated
  • subscription.renewal_upcoming
  • subscription.resumed
  • subscription.trial_ending
  • subscription.updated
  • subscription_delivery_migration.completed
  • subscription_payment_retry.created
  • subscription_payment_retry.failed
  • subscription_payment_retry.succeeded
after_event_idstring

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

curl https://api.withflintpay.com/v1/webhook-events/stream \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?