Modulr Webhook Ingestion

The Direct Debit service exposes a public endpoint that receives lifecycle event callbacks from Modulr. This is how the service learns about mandate state changes, collection outcomes, and payment completions — without polling the Modulr API.

Endpoint

POST /api/webhooks/modulr

This endpoint must be registered as the webhook destination in your Modulr configuration.

Security — HMAC Signature Verification

Every inbound request is authenticated using an HMAC signature supplied by Modulr in the request headers. The service verifies this signature before processing the payload. Requests that fail verification receive a 401 response and are not processed further.

Ensure the shared HMAC secret is kept in sync between your Modulr account settings and the service's environment configuration.

Supported Event Types

Event	Description
mandate.auddis_accepted	Modulr has confirmed the mandate was accepted via AUDDIS/BACS. The mandate transitions to active.
mandate.auddis_rejected	The mandate submission was rejected by AUDDIS. The mandate transitions to a failed state and the tenant may need to resubmit.
collection.settled	A BACS collection has successfully settled. Triggers the sweep of funds from the Modulr collection account to the Griffin holding account.
collection.returned	A collection has been returned (e.g. insufficient funds, account closed, mandate cancelled at the bank). Triggers clawback handling logic.
payment.completed	A payment has completed successfully.

Processing Model

The endpoint is designed for high reliability:

1. Receive — The raw payload is written to the database immediately on receipt.
2. Dispatch — The event is forwarded to the appropriate Inngest background function.
3. Respond — A 200 OK is returned to Modulr straight away, before any downstream processing begins.

All business logic (mandate state updates, fund sweeps, alerts) runs asynchronously via Inngest. This means slow or failed downstream processing does not cause Modulr to retry delivery unnecessarily.

Raw Payload Storage

Every webhook payload — including any events that cannot be matched to a known event type — is stored in its raw form in the database. This provides a full audit trail and makes it straightforward to debug unexpected behaviour or replay events during development.

Response Codes

Status	Meaning
200 OK	Payload received, stored, and dispatched for async processing.
401 Unauthorized	HMAC signature verification failed. Payload was not processed.
400 Bad Request	Malformed request body.