Webhooks

Webhooks allow you to receive real-time notifications about events in your Flintn account.

Overview

Instead of polling the API for changes, you can configure webhook endpoints to receive HTTP POST requests when events occur. This enables you to build reactive integrations that respond immediately to subscription and transaction lifecycle events.

Supported Events

Subscription Events

Event	Description
SUBSCRIPTION_ACTIVATED	A new subscription has been activated
SUBSCRIPTION_RENEWED	Subscription successfully renewed for a new billing period
SUBSCRIPTION_CANCELLED	Subscription has been cancelled
SUBSCRIPTION_CANCELLATION_SCHEDULED	Subscription cancellation has been scheduled for end of billing cycle
SUBSCRIPTION_EXPIRED	Subscription has expired
SUBSCRIPTION_BILLING_RETRY	A billing retry attempt was made for a failed payment

Transaction Events

Event	Description
TRANSACTION_PENDING	Transaction is pending processing
TRANSACTION_AUTHORIZED	Transaction has been authorized
TRANSACTION_DECLINED	Transaction was declined
TRANSACTION_FAILED	Transaction failed to process
TRANSACTION_VOIDED	Transaction has been voided
TRANSACTION_SETTLED	Transaction has been settled
TRANSACTION_REFUNDED	Transaction has been fully refunded
TRANSACTION_PARTIALLY_REFUNDED	Transaction has been partially refunded

Webhook Payload

Each webhook delivery includes a JSON payload with event details:

{
  "event_type": "TRANSACTION_SETTLED",
  "event_id": "6fe45cc8-503c-4d23-a9fd-724a206b3f7a",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0",
  "data": {
    "id": "1562d729-0415-4750-a333-3669f49b643a",
    "payment_id": "b282852c-1421-4ef9-bce6-28a3d25216d6",
    "merchant_id": "5f5094c6-c8cb-4f15-8b0e-8b5b0b1bea94",
    "amount": 29.99,
    "currency": "USD",
    "status": "SETTLED"
  }
}

Security

All webhook requests include a signature header (X-Signature-Primary) that you should verify to ensure the request came from Flintn. The signature is a Base64-encoded HMAC-SHA256 hash of the request body, computed using your webhook secret.

See Webhook Secrets for details on managing your signing secret, and Configure Webhooks for verification code examples.

Next Steps

• Configure Webhooks - Learn how to set up webhook endpoints

• Webhook Secrets - Manage your webhook signing secret