Notifications enable your platform to find out about events as they happen.

We currently provide over two notification channels, webhooks and emails.

  • Webhook: If you send a request for a notification that is a webhook, then the notifications will be as webhooks and you will need to build a listener
  • Email: This will create a notification that will be sent to the email addresses listed. Emails do not need a listener or event handler, as the alert will be sent to all email addresses specified. It is best practice to use group email addresses, as they can be changed when people need to be removed or added without needing to edit the notification itself

These are setup at a customer level and apply to all accounts

Notification TypeDescriptionChannel AvailabilitySubscription Level
Account StatementA notification to alert you that new statements are available for your accounts. This is typically received in the first few days of a new month.EmailCustomer
Balance HighWhen one of your Accounts has a balance that goes over a specified amount you are alertedEmailCustomer
Balance LowWhen one of your accounts has a balance that goes below a specified amount you are alertedEmailCustomer
Pending PaymentsWhen any of your accounts have payments pending to be sent due to needing approval, waiting for funds or waiting for a set date to be sent this email gives a summary of those payments that are pending to be sent.EmailCustomer
Scheduled BalanceA periodic notification of the balance of your Accounts sent at a specified day and timeEmailCustomer
Card Authorisation - CARDAUTHA notification to alert you that there has been a new or updated card authorisationWebhookCustomer
Card Creation - CARDCREATIONA notification to alert you of the status of a create physical card request, this is only available for Physical cards and not virtual cards.WebhookCustomer
Customer Verification Status - CUSTVSTATAs a partner on the Modulo Platform if Modulr handle your KYC/KYB process this webhook will be sent to notify you when there are changes to a customer in this processWebhookPartner
Direct Debit Mandate Status - DDMANDATEA notification to alert you of any changes to the status of a Direct Debit Mandate.WebhookCustomer
Direct Debit Failed Claim - DD_FAILED_CLAIMA notification to alert you that a DD claim has failed. Sent at around 5pm on the day the collection is due.WebhookCustomer
Direct Debit Funds Returned - DD_FUNDS_RETURNEDA notification to alert partners that the funds associated with a failed DD have been returned by the scheme and credited in their nominated account.

Returned funds notification is one per nominated account and not per collection.
Direct Debit Incoming Debit - DD_INCOMING_DEBITA notification to alert partners that a collection has been received, accepted, and a debit of the client account will be attempted in the pre-defined time period.

We send 1 webhook per collection.
Inbound Payment - PAYINWhen one of your accounts is successfully funded you are alertedEmail, WebhookCustomer
Card Refund - PAYINWhen there's a new refund in a card that's associated with one of your accountsWebhookCustomer
Outbound Payment - PAYOUTWhen one of your Accounts has a successful payment out of it you are alertedWebhookCustomer
Card Settlement - PAYOUTWhen there's a new settlement in a card that's associated with one of your accountsWebhookCustomer
Outbound Reversed Payment -
A notification to alert that the funds associated with a reversed payment have been returned as a separate operationWebhookCustomer
Upcoming BACs Credit - UPCOMING_CREDITA notification to alert you that there will be a BACs credit applied to the account. This is triggered on Day 2 of the BACs process prior to the actual credit on the account happening on Day 3WebhookCustomer
Account status change - ACCOUNT_STATUS_CHANGENotification of change for when an account changes status, e.g. BLOCKED to ACTIVEWebhookCustomer

Please see the API Reference section for more details on how to set up the notifications

So as an example you've decided that it would be really useful for your system to be alerted when you get any funds paid in to your accounts, now what do you do?

Webhooks - An Introduction

A Webhook, in simple terms, is a user-defined HTTP callback. It is a mechanism for the system to notify you about an event. How does it notify you? By doing an HTTP POST to the Webhook (i.e. the Web URL that you define). In terms of implementation, you can write an API endpoint that is capable of receiving an HTTP POST in an application stack of your choice. Remember in live this must be reliable and resilient if you are to depend on it for information.

The advantage of a Webhook is that there is no persistent open connection to the system where you keep filtering for events that you are interested in. It is an asynchronous mechanism where you will wait for the system to notify you. The HTTP POST payload will contain the details of the event.

Webhook security

We sign the POST request with an HMAC digest, using a secret that you provide. This can be set when registering the endpoint for the webhook type of notification. It is required that you validate this signature, particularly if you are acting upon these events to authorise actions in your system. The method of calculation of the hmac signature is the same as in HMAC Signatures / Authorisation header calculation
For webhook requests that are sent from us to you, we use the webhook id as the key and the secret you have provided when creating the webhook to sign the webhook.

Setting up a webhook

Listen and Receive

Firstly, you need to set up the ability for your system to do something and make sure you have a URL ready to listen for any alerts. In a test example here you could post an alert from Modulr in to RequestBin but obviously this would be your system listening when you build your endpoint.

In our example for notifications of payments in, once you create an endpoint url, you need to set this webhook up in Modulr for your customer id using Set up a Notification for a Customer, using channel WEBHOOK and type PAYIN
You should now be all set with the Incoming Webhook configured and waiting for Modulr to message it when receiving a payment in.

To test this you can trigger a dummy sandbox payment in using Pay into an account and then view your RequestBin for the webhook

Responding to Modulr Webhooks

When built in to your system to acknowledge receipt of a webhook, your endpoint should return a 2XX HTTP status code. Any other information you return in the request headers or request body will be ignored.

If we do not receive a 2XX response to our POST request, we will retry the request with exponential back off, to a maximum of 5 retries.

RetryTime after first failure
1st Retry1 Minute
2nd Retry5 Minutes
3rd Retry25 minutes
4th Retry2 hours 5 minutes
5th Retry10 hours 25 minutes

After 5 tries we will not process the event further. Therefore you should not rely on webhooks as the sole means for reconciliation of the completeness of financial events into your system, particularly if you are aware of any recent issues you may have had with your webhook listener reliability.

Webhook duplicate checks

As mentioned above we have the ability to retry webhooks up to a maximum of 5 times automatically. This highlights the importance of ensuring you are handling webhooks correctly and checking that each webhook is unique to your system to prevent any undesired behaviours like processing a webhook twice for the same event.

For example we recommend in regards to the PAYIN or PAYOUT webhook to utilise PaymentId as your main duplicate check, as there are times where the EventId could change or in the event of a failed payment the TransactionId would be empty.

Depending on the Payment scheme the PaymentId could following different patterns but will always represent a unique indentifier.

Webhook parsing

We recommend all of our clients when implementing handling of webhooks to utilise a lenient json parser. This is to ensure as we add new functionality and richer information to our webhooks that your system does not start to fail the processing of the webhooks.

No longer need your notification?

So, you no longer want to get notified when money goes into your accounts? The easiest way to do this is to inactivate the webhook channel alert. You will need to know the ID {id} of the webhook that was given to you in the response when creating the notification and use the PUT endpoint to change the status from ACTIVE to INACTIVE. You will also need to know the customer id {cid}.

If you change you mind you can always re-activate the webhook using the same endpoint. You'll need to change the status back to ACTIVE and make sure the 'destinations' parameter is set to the URL you have set up to listen out for an alert.

Payment type definitions

Payment types information can be found here