Webhooks¶

Webhooks deliver real-time, signed event notifications to your server whenever a Transaction, Subclient, Subclient Account, or other resource changes state. They are the primary mechanism for keeping your platform in sync with GIB's view of the world. Manage subscriptions via the Webhooks API (list, create, update, audit history, delivery-event inspection, and testWebhook to verify an endpoint).

For human-facing alerts (email, dashboard inbox), see Notifications.

Subscriptions¶

Each subscription is configured with:

• A target URL — your endpoint that receives HTTP POST requests
• An event filter — a regex matched against event types (e.g. ^outbound_ach_transaction_.*$ matches all outbound ACH events; ^subclient_.*$ matches all Subclient lifecycle events)
• A signing secret — used to verify each delivered payload

Manage subscriptions through the Webhooks API. You can hold multiple subscriptions for the same Company; a common pattern is one subscription for transaction events going to your main payment service and another for Subclient events going to your onboarding service.

Event types¶

Transactions¶

transfer_direction vs data_direction: Event type names use transfer_direction (inbound/outbound) — money flow relative to your account. This is distinct from data_direction (incoming/outgoing/internal) — which describes file origin. See Transactions → Fields for the full distinction.

Transaction events follow the format {direction}_{type}_transaction_{state}:

<type> is one of: ach, wire, wire20022, book, icl

Allowed states: pending_settlement, created, processing, processed, posted, updated, failed, canceled, under_review

Returns and NOCs ride the same event stream — identify them via the Transaction's transfer_type field.

Subclients¶

subclient_created, subclient_pending, subclient_approved, subclient_rejected, subclient_updated

Regex filter examples¶

• ^outbound_ach_transaction_.*$ — all outbound ACH state changes
• .*_transaction_posted$ — every posted event (any direction, any rail)
• ^subclient_.*$ — all Subclient lifecycle events

For the full event-type enum and payload schemas, see API reference → Webhooks.

Authentication & signature verification¶

Every webhook payload is signed with HMAC-SHA256 using a per-subscription secret. The signature is delivered in the Signature HTTP header.

To verify, compute an HMAC-SHA256 over the raw request body using the subscription secret as the key, then compare against the Signature header value. Reject the payload if they don't match.

import base64, hmac, hashlib

def verify(subscription_secret_b64: str, raw_body: bytes, signature_header: str) -> bool:
    secret = base64.b64decode(subscription_secret_b64)
    expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Allowlist GIB's webhook delivery IPs at your endpoint; see the IP list in API reference → Webhooks.

Delivery semantics¶

• At-least-once delivery. Every event carries a unique event_id. The same event can be delivered more than once — use event_id as a dedupe key in your handler.
• Per-resource FIFO ordering. Within a single subscription, events for the same resource (Transaction, Subclient, etc.) are delivered in order. Events across different resources may arrive out of order relative to each other.
• 2XX in 10 seconds. A 2XX response within 10 seconds is a successful delivery. Anything else triggers a retry. Best practice: return 2XX immediately on receipt, then process asynchronously to avoid timeout-induced retries.

Retries and backoff¶

Failed deliveries retry up to 10 times over 12 hours:

2s → 5s → 10s → 10m → 30m → 1h → 3h → 6h → 12h

After 10 failed attempts the event is given up. To avoid silent data loss:

• Subscribe to webhook.delivery_failed on a separate subscription so you know when an endpoint is down
• Configure email delivery (see Notifications) for mandatory events (ACH returns, NOCs, reconciliation discrepancies) so they always reach a human even during webhook outages

Troubleshooting¶

Every subscription has an event trace in the dashboard showing every delivery attempt (including failures) with response status, headers, and timing. Use the trace to diagnose regressions when an endpoint silently starts rejecting deliveries.

Related concepts¶

• Notifications, the complementary email and dashboard notification system
• Transactions, the primary source of webhook events
• Subclients, lifecycle events
• Returns, return events delivered via the standard transaction event stream
• Idempotency, at-least-once delivery means your handlers must be idempotent
• Security, signature verification and IP allowlisting