Webhooks

Infinite delivers webhooks as signed HTTPS POST requests with automatic retries. Webhooks allow you to receive real-time notifications about events that occur in your account, such as when a customer is created, an invoice is paid, or a transfer is completed.

Overview

Webhooks are HTTP POST requests sent to your server when specific events occur. Each webhook event includes:

Event ID: Unique identifier for idempotency
Event Type: The type of event (e.g., customer.created, invoice.paid)
Timestamp: When the event occurred
Organization ID: The organization that triggered the event
Data: The event payload with relevant information

Event Catalog

Browse every available event type — with descriptions and sample payloads — in the Event Catalog in your console under Developer → Webhooks. Events are grouped by domain:

Customer Events: customer.created, customer.updated, customer.verified, customer.status_changed, customer.deleted, and more
Transfer Events: transfer.created, transfer.processing, transfer.updated, transfer.completed, transfer.failed, transfer.cancelled, transfer.refund_initiated, transfer.refund_completed, transfer.reversed
Invoice Events: invoice.created, invoice.sent, invoice.paid, invoice.cancelled, invoice.overdue
Verification Events: verification.session.created, verification.session.submitted, verification.session.completed, verification.session.failed, verification.link.sent, verification.session.expired
FX Events: fx_trade.created, fx_trade.completed, fx_quote.expired, and more
Agent Events: agent.created, agent.updated, agent.limit_reached, agent.revoked — transfer.* payloads also carry agentId when an agent key made the transfer

For transfers where funds have already been received, operational issues are sent as transfer.updated with data.status set to IN_REVIEW while Infinite reviews or resolves the transfer. transfer.failed is only sent when the transfer fails before funds are received.

Setting Up Webhooks

1. Create a Webhook Endpoint

Use the Create Webhook Endpoint API to register your webhook URL:

import requests

response = requests.post(
    'https://api.infinite.dev/v1/webhooks/endpoints',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://your-server.com/webhooks',
        'description': 'Production webhook endpoint',
        'filterTypes': ['customer.created', 'invoice.paid'],
    },
)

const response = await fetch('https://api.infinite.dev/v1/webhooks/endpoints', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-server.com/webhooks',
    description: 'Production webhook endpoint',
    filterTypes: ['customer.created', 'invoice.paid'],
  }),
});

export INFINITE_API_KEY=YOUR_API_KEY
infinite api POST /v1/webhooks/endpoints --body '{
  "url": "https://your-server.com/webhooks",
  "description": "Production webhook endpoint",
  "filterTypes": ["customer.created", "invoice.paid"]
}'

Create a webhook endpoint at https://your-server.com/webhooks for customer.created and invoice.paid events, described as "Production webhook endpoint".

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X POST https://api.infinite.dev/v1/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks",
    "description": "Production webhook endpoint",
    "filterTypes": ["customer.created", "invoice.paid"]
  }'

2. Configure Event Filtering

You can specify which event types to receive using the filterTypes array. Omit it (or pass an empty array) to receive all event types, including new ones as they launch. To receive only specific events:

{
  "url": "https://your-server.com/webhooks",
  "description": "Customer events only",
  "filterTypes": ["customer.created", "customer.updated", "customer.verified"]
}

3. Manage Endpoints

List endpoints: GET /v1/webhooks/endpoints
Update endpoint: PUT /v1/webhooks/endpoints/{endpointId} (supports enabling/disabling with disabled)
Delete endpoint: DELETE /v1/webhooks/endpoints/{endpointId}
Get signing secret: GET /v1/webhooks/endpoints/{endpointId}/secret
Rotate signing secret: POST /v1/webhooks/endpoints/{endpointId}/secret/rotate — the previous secret stays valid for 24 hours so you can roll over without dropping deliveries

You can also manage endpoints in the console under Developer → Webhooks.

Webhook Payload Structure

All webhook events follow this structure:

{
  "id": "evt_1234567890abcdef",
  "timestamp": "2026-09-15T10:30:00Z",
  "apiVersion": "1.0",
  "organizationId": "org_abc123",
  "type": "customer.created",
  "data": {
    // Event-specific data
  }
}

Example: Customer Created Event

{
  "id": "evt_1234567890abcdef",
  "timestamp": "2026-09-15T10:30:00Z",
  "apiVersion": "1.0",
  "organizationId": "org_abc123",
  "type": "customer.created",
  "data": {
    "id": "cus_1234567890",
    "customerName": "Acme Corporation",
    "email": "contact@acme.com",
    "type": "BUSINESS",
    "status": "PENDING",
    "countryCode": "US",
    "createdAt": "2026-09-15T10:30:00Z",
    "updatedAt": "2026-09-15T10:30:00Z"
  }
}

Example: Invoice Paid Event

{
  "id": "evt_9876543210fedcba",
  "timestamp": "2026-09-15T11:45:00Z",
  "apiVersion": "1.0",
  "organizationId": "org_abc123",
  "type": "invoice.paid",
  "data": {
    "id": "inv_1234567890",
    "customerId": "cus_1234567890",
    "amount": 100000,
    "currency": "USD",
    "status": "PAID",
    "paidAt": "2026-09-15T11:45:00Z",
    "createdAt": "2026-09-01T10:00:00Z"
  }
}

Verifying Webhooks

Every delivery is signed following the Standard Webhooks specification and includes webhook-id, webhook-timestamp, and webhook-signature headers. Verify these signatures to ensure the webhook is legitimate. Retrieve your endpoint’s signing secret (whsec_...) with the Get Signing Secret API or from the console under Developer → Webhooks → Signing secret.

Using a Verification Library

The easiest way to verify webhooks is with a Standard Webhooks library: Node.js:

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.WEBHOOK_SIGNING_SECRET);

// Throws if the signature is invalid
const payload = webhook.verify(req.body, {
  'webhook-id': req.headers['webhook-id'],
  'webhook-timestamp': req.headers['webhook-timestamp'],
  'webhook-signature': req.headers['webhook-signature'],
});

Python:

from standardwebhooks import Webhook

webhook = Webhook(webhook_secret)

# Raises if the signature is invalid
payload = webhook.verify(
    data=request.body,
    headers={
        'webhook-id': request.headers['webhook-id'],
        'webhook-timestamp': request.headers['webhook-timestamp'],
        'webhook-signature': request.headers['webhook-signature'],
    }
)

Manual Verification

To verify manually, compute the signed content as {webhook-id}.{webhook-timestamp}.{raw request body}, HMAC-SHA256 it with the base64-decoded portion of your signing secret (the part after whsec_), and base64-encode the result. Compare it against the v1, entries in the webhook-signature header using a constant-time comparison, and reject deliveries whose timestamp is more than a few minutes old to prevent replay attacks.

Delivery History & Replay

Inspect and replay deliveries programmatically:

List messages: GET /v1/webhooks/messages — newest first, with cursor pagination. Filter by endpointId (adds per-endpoint delivery status), eventTypes, tag (resource IDs such as a transfer or customer ID), and time range.
Get a message: GET /v1/webhooks/messages/{messageId} — includes the payload and every delivery attempt with HTTP status and response body. The message ID matches the webhook-id header on the delivery.
Resend a message: POST /v1/webhooks/messages/{messageId}/resend — redelivers the original payload to every enabled endpoint subscribed to the event type, or a single endpoint via endpointId.
Replay failed deliveries: POST /v1/webhooks/endpoints/{endpointId}/recover — redelivers everything that failed since a timestamp. Useful after an outage on your receiver.

import requests

# Replay all failed deliveries from the last 24 hours
response = requests.post(
    'https://api.infinite.dev/v1/webhooks/endpoints/ep_123/recover',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={'since': '2026-08-16T14:00:00Z'},
)

// Replay all failed deliveries from the last 24 hours
const response = await fetch(
  'https://api.infinite.dev/v1/webhooks/endpoints/ep_123/recover',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ since: '2026-08-16T14:00:00Z' }),
  },
);

export INFINITE_API_KEY=YOUR_API_KEY
# Replay all failed deliveries from the last 24 hours
infinite api POST /v1/webhooks/endpoints/ep_123/recover --body '{
  "since": "2026-08-16T14:00:00Z"
}'

Replay failed webhook deliveries for endpoint ep_123 since 2026-08-16T14:00:00Z.

# Infinite MCP is read-only today — run the CLI tab to execute.

# Replay all failed deliveries from the last 24 hours
curl -X POST https://api.infinite.dev/v1/webhooks/endpoints/ep_123/recover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "since": "2026-08-16T14:00:00Z" }'

Message history and payloads are retained for 90 days. The same delivery feed — with filters, payload inspection, and one-click resend — is available in the console under Developer → Webhooks → Deliveries.

Best Practices

Idempotency

All webhook events include an id field, and replays redeliver the original event unchanged. Use the ID to implement idempotency in your webhook handler:

async function handleWebhook(event) {
  // Check if we've already processed this event
  const existing = await db.findEventById(event.id);
  if (existing) {
    return; // Already processed
  }

  // Process the event
  await processEvent(event);

  // Store the event ID
  await db.saveEventId(event.id);
}

Retry Logic

Infinite automatically retries failed webhook deliveries with exponential backoff. Your endpoint should:

Return 200 OK immediately after receiving the webhook
Process the event asynchronously
Handle errors gracefully

Security

Always verify webhook signatures
Use HTTPS for your webhook endpoints
Store signing secrets securely (environment variables, secrets manager)
Monitor your delivery history for suspicious activity

Error Handling

If your endpoint returns a non-2xx status code, the delivery is retried. If you want to acknowledge receipt but process later:

app.post('/webhooks', async (req, res) => {
  // Return 200 immediately
  res.status(200).send({ received: true });

  // Process asynchronously
  await processWebhookAsync(req.body);
});

Testing Webhooks

Send an example payload of any event type to an endpoint from the console: Developer → Webhooks → Endpoints → Send test event. The delivery shows up in the Deliveries feed like any other event, including the response your server returned.

Need Help?

Browse the Event Catalog in your console for all available events and sample payloads
Review the API Reference for endpoint details

Get started

Core Concepts

Guides

Overview

Event Catalog

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Configure Event Filtering

3. Manage Endpoints

Webhook Payload Structure

Example: Customer Created Event

Example: Invoice Paid Event

Verifying Webhooks

Using a Verification Library

Manual Verification

Delivery History & Replay

Best Practices

Idempotency

Retry Logic

Security

Error Handling

Testing Webhooks

Need Help?

​Overview

​Event Catalog

​Setting Up Webhooks

​1. Create a Webhook Endpoint

​2. Configure Event Filtering

​3. Manage Endpoints

​Webhook Payload Structure

​Example: Customer Created Event

​Example: Invoice Paid Event

​Verifying Webhooks

​Using a Verification Library

​Manual Verification

​Delivery History & Replay

​Best Practices

​Idempotency

​Retry Logic

​Security

​Error Handling

​Testing Webhooks

​Need Help?

Overview

Event Catalog

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Configure Event Filtering

3. Manage Endpoints

Webhook Payload Structure

Example: Customer Created Event

Example: Invoice Paid Event

Verifying Webhooks

Using a Verification Library

Manual Verification

Delivery History & Replay

Best Practices

Idempotency

Retry Logic

Security

Error Handling

Testing Webhooks

Need Help?