Webhook Events: DD Lifecycle

The Direct Debit service emits webhook events at each significant stage of the mandate, collection, funds, and alerting lifecycle. This lets your application react to changes in real time — without polling the API.

Overview

Webhook events are delivered over HTTPS to a configured endpoint. Each event carries a consistent payload containing the organisation ID, resource ID, status, amount, and timestamp. Agents choose which events to subscribe to via the webhook config UI.

Subscribing to Events

Navigate to Settings → Webhooks in your dashboard to:

Add or update your webhook endpoint URL
Select the specific events you want to receive
View recent delivery logs and retry failed deliveries

Only events you have explicitly subscribed to will be delivered to your endpoint.

Event Reference

Mandate Events

Mandate events track the full AUDDIS registration lifecycle for a Direct Debit mandate.

`mandate.created`

Fired when a tenant successfully submits the mandate form. The mandate is pending AUDDIS registration at this point — no collections will be attempted yet.

`mandate.active`

Fired when AUDDIS registration is confirmed and the mandate is live. Collections can now be scheduled against this mandate.

`mandate.rejected`

Fired when a mandate is rejected — typically due to invalid bank details or an AUDDIS failure. Your application should notify the agent and optionally trigger the gatekeeping flow.

`mandate.cancelled`

Fired when a mandate is cancelled by either the agent or the tenant. No further collections will be attempted.

`mandate.suspended`

Fired when a mandate is suspended (e.g. following a failed collection or manual agent action). The mandate can be reactivated via the API.

Collection Events

Collection events track each individual BACS collection attempt through to settlement.

`collection.scheduled`

Fired when a collection is created and queued for a future BACS submission date.

`collection.collected`

Fired when funds have been successfully debited from the tenant's bank account and received in the Modulr collection account.

`collection.failed`

Fired when a collection attempt fails — for example due to insufficient funds, a closed account, or a cancelled mandate. Your application should surface this to the agent promptly.

`collection.clawback`

Fired when a tenant's bank reverses a previously collected payment. The clawback reserve in the Griffin holding account will be affected. Monitor this event to track reserve movements.

Funds Events

Funds events track the sweep and forward stages of the fund flow.

`funds.swept`

Fired when collected funds have been moved from the Modulr collection account into the Griffin DD holding account. The hold period begins from this point.

`funds.forwarded`

Fired when funds have cleared the hold period and clawback reserve check, and have been transferred from the Griffin holding account to the agent's client account.

Alert Events

Alert events reflect the monitoring and threshold system.

`alert.raised`

Fired when a configured threshold is breached — for example:

Mandate creation rate exceeds the configured limit
Daily or weekly collection amount exceeds configured thresholds
Clawback reserve drops below the minimum

`alert.acknowledged`

Fired when an agent or admin marks an alert as acknowledged.

Event Payload

All events use the same payload envelope:

{
  "event": "funds.forwarded",
  "orgId": "org_abc123",
  "resourceId": "fwd_def456",
  "status": "forwarded",
  "amount": 120000,
  "timestamp": "2025-06-02T11:30:00Z"
}

Field	Type	Description
`event`	`string`	The event type (e.g. `mandate.created`, `collection.failed`)
`orgId`	`string`	The organisation (letting agent) this event belongs to
`resourceId`	`string`	Unique ID of the affected resource
`status`	`string`	Status of the resource at the time the event was emitted
`amount`	`integer` \| `null`	Amount in pence (GBP). Present for collection and fund events; `null` for mandate and alert events
`timestamp`	`string`	ISO 8601 UTC datetime of the event

Note: Amounts are always expressed in pence. Divide by 100 to display in pounds (e.g. 120000 = £1,200.00).

Event Delivery

Events are delivered via HTTP POST to your configured webhook URL
Delivery uses the existing webhook infrastructure — endpoint configuration, signing secrets, retry logic, and delivery logs are all managed through the webhook config UI
Delivery is per-organisation: events for orgId: org_abc123 are only delivered to that organisation's configured endpoint

Common Integration Patterns

Gatekeeping on mandate failure

Listen for mandate.rejected and mandate.cancelled to trigger access restriction logic in your application (e.g. block tenant portal access).

Reconciliation

Listen for collection.collected and funds.forwarded to update your ledger or notify landlords that rent has been received.

Clawback handling

Listen for collection.clawback to trigger agent notifications and review workflows.

Alert forwarding

Listen for alert.raised to forward fraud or threshold breach notifications into your own alerting pipeline (e.g. Slack, PagerDuty).