Webhooks

In financial infrastructure, event-driven communication can help applications respond to transaction updates, provider notifications, and changes in operational state.

This guide explains webhook integration principles relevant to Infrarails and its connected services.

Understanding webhooks

A webhook is typically an HTTP request sent from an event-producing service to a configured receiving endpoint.

Instead of repeatedly requesting information, an application can receive notifications when relevant events occur.

sequenceDiagram
    participant P as External Provider
    participant W as Webhook Receiver
    participant L as Infrarails Ledger
    participant A as Application

    P->>W: Event notification
    W->>W: Authenticate and validate
    W->>W: Check duplicate event
    W->>L: Apply supported accounting workflow
    L-->>W: Operation result
    W->>A: Update application state

This is a conceptual processing flow. The actual webhook availability, delivery format, and processing order depend on the integration.

Common event categories

Financial integrations may produce events involving:

• Transaction creation.
• Transaction status changes.
• Incoming payments.
• Outgoing payment updates.
• Account changes.
• Provider balance changes.
• Payment failures.
• Settlement notifications.

These are examples of event categories, not a published list of Infrarails webhook event types.

Consult the relevant API or provider documentation for supported events.

Webhook payloads

Webhook notifications generally contain information identifying the event and the affected resource.

An illustrative event structure is:

{
  "event_id": "evt_example_001",
  "event_type": "transaction.updated",
  "created_at": "2026-10-19T10:00:00Z",
  "data": {
    "transaction_id": "txn_example_001",
    "status": "COMPLETED"
  }
}

This example demonstrates a possible event structure. It is not an actual Infrarails webhook schema.

Webhook security

Webhook endpoints should authenticate the sender before accepting an event as trusted.

Depending on the provider, authentication may use:

• Cryptographic signatures.
• Shared secrets.
• Authenticated transport.
• Provider-specific authorization mechanisms.

The exact verification procedure must follow the provider's documented requirements.

Do not assume that every webhook uses the same signature algorithm or header format.

Duplicate delivery

Webhook providers may deliver the same event more than once.

Applications should implement duplicate-event protection.

Where an event has a stable identifier, the receiver can store that identifier and use it to recognize repeated deliveries.

Duplicate protection should also account for the underlying business operation.

For example, receiving the same payment notification twice must not create two financial credits.

Event ordering

Events may arrive out of order.

An application might receive a later status update before an earlier event due to network or delivery delays.

Do not rely on event arrival order unless the provider explicitly guarantees it.

Where necessary, retrieve the authoritative operation state before applying a financial update.

Reliable processing

A webhook receiver should be designed to handle temporary failures.

A typical processing approach is:

1. Receive the event.
2. Verify its authenticity.
3. Validate the payload.
4. Identify the affected resource.
5. Check for duplicate processing.
6. Record or enqueue the event.
7. Execute the supported business workflow.
8. Store the processing outcome.

The HTTP acknowledgment strategy should follow the sender's documented delivery contract.

Webhooks and ledger transactions

Incoming provider events may trigger internal ledger operations.

For example, a confirmed incoming payment event may require a corresponding accounting transaction.

Before creating a ledger transaction, the integration should verify that the event is eligible and has not already been processed.

The correct accounting action depends on the event type, provider, and business rules.

Monitoring

Webhook processing should be observable.

Useful information includes:

• Event identifier.
• Provider.
• Event type.
• Receipt timestamp.
• Processing result.
• Associated ledger transaction.
• Error details.

Sensitive credentials and unnecessary personal information should not be stored in logs.

Best practices

• Authenticate incoming webhook events.
• Validate payloads before processing.
• Handle duplicate deliveries safely.
• Do not assume events arrive in order.
• Separate event receipt from long-running processing where appropriate.
• Preserve relevant provider identifiers.
• Reconcile uncertain financial outcomes.
• Monitor failed processing attempts.

Next steps

Continue with Reconciliation to understand how external provider operations are compared with internal ledger records.