Outbound Webhook Events for the DD Lifecycle

Available from: v1.0.58

The Direct Debit collection service can push real-time event notifications to any HTTP endpoint you configure. This means your application — whether agentOS or any other consumer — never needs to poll for status changes. Instead, the service delivers a structured payload the moment something meaningful happens.

How Webhooks Work

Configure an endpoint — In your agent dashboard, add one or more HTTPS URLs that the service should deliver events to.
Choose your subscriptions — Select which event types you want to receive. You can subscribe to all events or only a specific subset.
Receive payloads — When a subscribed event fires, the service sends an HTTP POST request to your endpoint with a JSON body containing all relevant entity data.
Respond with 2xx — Your endpoint should return any 2xx status code to acknowledge receipt. Non-2xx responses will be treated as a delivery failure.

Available Events

Mandate Events

`mandate.created`

Fired when a tenant completes and submits the mandate form. Use this to update your records as soon as a new mandate enters the system.

`mandate.active`

Fired when a mandate is successfully registered via AUDDIS and is live for collections. This is the signal that collections can be scheduled.

`mandate.cancelled`

Fired when a mandate is cancelled — whether by the agent, the tenant, or the tenant's bank. If your application gates access based on mandate status (e.g. blocking tenant portal access), listen to this event.

`mandate.suspended`

Fired when a mandate is suspended. Suspended mandates will not generate collections until reactivated.

`mandate.failed`

Fired when a mandate fails to register or cannot be processed. Use this to trigger remediation flows (e.g. prompting the tenant to re-submit).

Collection Events

`collection.submitted`

Fired when a collection request is submitted to Modulr via BACS. This marks the start of the BACS processing cycle for a given payment.

`collection.collected`

Fired when funds have been successfully debited from the tenant's account and received into the Modulr collection account. This triggers the sweep to the Griffin DD holding account.

`collection.failed`

Fired when a collection attempt fails (e.g. insufficient funds, closed account, payer cancellation). Use this to alert agents and decide whether to retry or take further action.

`collection.returned`

Fired when a previously collected payment is reversed — typically a bank-initiated clawback or an indemnity claim by the payer. Monitor this event closely as it affects the clawback reserve balance.

Funds Events

`funds.forwarded`

Fired when collected funds are released from the Griffin DD holding account and forwarded into the agent's Griffin client account. This signals that the funds are now available to the agent.

Alert Events

`alert.raised`

Fired when the service's monitoring system detects a threshold breach, such as:

Mandate creation rate exceeding the configured limit
Daily or weekly collection amounts exceeding thresholds
Clawback reserve dropping below the minimum

Listen to this event to surface alerts in your own application UI, or to trigger your own notification flows.

Payload Structure

All webhook payloads share a common envelope:

{
  "event": "mandate.active",
  "occurred_at": "2025-06-01T10:30:00Z",
  "data": {
    // Full entity object relevant to the event
  }
}

event — The event type string (e.g. mandate.active).
occurred_at — ISO 8601 timestamp of when the event occurred.
data — The full entity object. For mandate events this will be the mandate record; for collection events, the collection record; for alert.raised, the alert record; and so on.

Configuring Webhooks in the Dashboard

Navigate to Settings → Webhooks in your agent dashboard.
Click Add Endpoint.
Enter the HTTPS URL of your receiving endpoint.
Select the events you wish to subscribe to.
Save. The endpoint is now active.

You can add multiple endpoints with different event subscriptions — for example, sending collection events to your payment reconciliation service and alert events to your ops monitoring system.

Multi-Tenancy

Webhook configuration is scoped per agent. Each agent's endpoints and subscriptions are entirely independent. One agent's events are never delivered to another agent's endpoints.

Event Reference Summary

Event	Category	Trigger
`mandate.created`	Mandate	Tenant submits mandate form
`mandate.active`	Mandate	AUDDIS registration confirmed
`mandate.cancelled`	Mandate	Mandate cancelled by any party
`mandate.suspended`	Mandate	Mandate suspended
`mandate.failed`	Mandate	Mandate registration or processing failure
`collection.submitted`	Collection	BACS submission sent to Modulr
`collection.collected`	Collection	Funds debited and received
`collection.failed`	Collection	Collection attempt failed
`collection.returned`	Collection	Payment reversed / clawback
`funds.forwarded`	Funds	Funds released to agent client account
`alert.raised`	Alert	Monitoring threshold breached