Configure Webhooks

Learn how to set up and manage webhook endpoints for your Flintn account.

Requirements

• Webhook endpoints must use HTTPS. HTTP endpoints are not supported.

• Your server must respond within 30 seconds with a 2xx status code.

• You must have a webhook secret to verify signatures.

Creating a Webhook Endpoint

Via Dashboard

1. Go to hub.flintn.com/developers

2. Navigate to Webhooks

3. Click Add Webhook

4. Enter a name for your webhook (e.g., "Production Orders")

5. Enter your HTTPS endpoint URL

6. Select the events you want to receive

7. Click Create

Via API

curl -X POST https://api.flintn.com/v1/merchants/webhooks \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "endpoint_url": "https://your-server.com/webhooks/flintn",
    "event_types": ["SUBSCRIPTION_ACTIVATED", "TRANSACTION_SETTLED"]
  }'

Verifying Webhook Signatures

All webhook requests include an X-Signature-Primary header containing a Base64-encoded HMAC-SHA256 signature. Always verify this signature to ensure the request came from Flintn and hasn't been tampered with.

JavaScript / Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'base64'),
    Buffer.from(expectedSignature, 'base64')
  );
}

// Express.js example
app.post('/webhooks/flintn', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature-primary'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);
  // Process the event...

  res.status(200).send('OK');
});

Python

import hmac
import hashlib
import base64

def verify_webhook_signature(payload: str, signature: str, secret: str) -> bool:
    expected = base64.b64encode(
        hmac.new(
            secret.encode('utf-8'),
            payload.encode('utf-8'),
            hashlib.sha256
        ).digest()
    ).decode('utf-8')
    return hmac.compare_digest(signature, expected)

# Flask example
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/flintn', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Signature-Primary')
    payload = request.get_data(as_text=True)

    if not verify_webhook_signature(payload, signature, os.environ['WEBHOOK_SECRET']):
        return 'Invalid signature', 401

    event = request.get_json()
    # Process the event...

    return 'OK', 200

Responding to Webhooks

Your endpoint should:

• Return a 2xx status code within 30 seconds

• Handle duplicate events idempotently (use the event_id field)

• Process events asynchronously if they require long-running operations

• Return a non-2xx status only if you want the delivery to be retried

Retry Policy

Failed webhook deliveries are automatically retried with exponential backoff:

Attempt	Delay
1	Immediate
2	5 minutes
3	30 minutes
4	2 hours
5	24 hours

After 5 failed attempts, the webhook is disabled. You can reactivate it from the dashboard once you've resolved the issue.

Note: 4xx client errors (except 429 Too Many Requests) are not retried, as they typically indicate a problem with your endpoint configuration rather than a temporary failure.

Managing Webhooks

Webhook Status

Status	Description
Active	Webhook receives events normally
Disabled	Webhook is temporarily paused; can be reactivated
Revoked	Webhook is permanently disabled

Disabling and Reactivating

You can temporarily disable a webhook if you need to perform maintenance on your endpoint. Disabled webhooks can be reactivated at any time. Events that occur while a webhook is disabled are not queued—they are simply not delivered.

Testing Webhooks

Use the dashboard at hub.flintn.com/developers to send test events to your endpoint during development. Test events use the same signature verification as production events.

For local development, use a tunneling service like ngrok to expose your local server with an HTTPS URL.

Next Steps

• Webhook Secrets - Learn how to manage your signing secret