All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Griffin Webhook Ingestion

Griffin Webhook Ingestion

Overview

The Direct Debit service listens for real-time payment events from Griffin via a dedicated webhook endpoint. When Griffin confirms a payment has been created, sent, or failed, the service updates internal state and — where appropriate — automatically triggers the next step in the fund flow.

Endpoint

POST /api/webhooks/griffin

This is a public endpoint. Griffin calls it automatically based on your configured webhook subscription in the Griffin dashboard.

Security — Signature Verification

Every incoming request is validated using Griffin's HMAC webhook signature before any processing occurs. Requests that are missing a signature or that fail verification are rejected with a 400 response and never processed.

Ensure the correct Griffin webhook secret is configured in your environment so signature verification can succeed.

Handled Events

EventDescription
payment.createdA payment has been initiated in Griffin. The corresponding holding_transaction record is updated to reflect the pending state.
payment.sentGriffin has confirmed the payment has been dispatched. The holding_transaction status is updated and the forward flow is automatically triggered if the payment was a sweep.
payment.failedThe payment attempt failed. The holding_transaction status is updated accordingly for investigation and retry logic.

All events are routed through Inngest for reliable, asynchronous processing — ensuring webhook delivery is acknowledged quickly and event handling is decoupled from the HTTP response.

Fund Flow Integration

The webhook endpoint is the trigger point for the final stage of the fund flow:

  1. Funds are swept from the Modulr collection account into the Griffin DD holding account.
  2. Griffin fires a payment.sent event once the sweep settles.
  3. The webhook endpoint receives and validates the event.
  4. An Inngest job is dispatched to execute the forward flow — moving funds from the Griffin holding account into the agent's Griffin client account.

This makes the end-to-end fund movement fully event-driven with no polling required.

Audit Trail

The raw payload of every webhook received is stored in the database, regardless of event type. This provides a complete, tamper-evident audit log of all Griffin-originated events for compliance and debugging purposes.

Configuration

To enable Griffin webhook delivery:

  1. Register the endpoint URL (https://<your-domain>/api/webhooks/griffin) in the Griffin dashboard under your webhook subscription settings.
  2. Subscribe to the following event types: payment.created, payment.sent, payment.failed.
  3. Copy the webhook signing secret from Griffin and configure it in your environment.