System Webhooks

We have introduced Webhooks V2 to SmarterPay Cloud. The key differences between the versions are as follows:

Version 1 Webhooks have one event per webhook. For example, the creation of a Bank Account, Mandate and a Payment will generate three events and will be sent out in three seperate Webhooks.

Version 2 Webhooks can have more than one event, across objects, per webhook. for example, the creation of a Bank Account, Mandate, and a Payment will generate three events but can all be sent out in one Webhook.
Please see “V2 Webhook Structure” for more details.

The number of Events in a single webhook varies, depending on how many Events are ready when the system sends out a Webhook.
The maximum number of Events that can be in a Webhook is set in the Subscription settings.

Version 2 Webhooks contain more information in an Event than a version 1 Webhook has.

The information in the version 2 event is also organised better, for example, Bank account information in a Mandate is in it's own Object rather than being just a bunch of properties on the Event.

Version 2 Webhooks contain an Idempotency Key that can be used to prevent duplicate actions occurring when SmarterPay Cloud is integrated to other platforms or Software.

All records now have a 19+ character Id. These new ids are always in the Id column on a v2 webhook. Any record created before this change will have a 'new' Id and a Legacy Id. This will be represented in the v2 webhook in the Id and Legacy Id fields. Any new records will not have a Legacy Id.

It is recommended that if you receive a webhook with a Legacy Id that you update your copy of the data with the new Id and use that moving forward. Legacy Ids will still continue to work with API, Portal and Search and there is no current timescale to deprecate these.

When SmarterPay cloud sends a webhook, to the endpoint defined in the Subscription settings, it is expecting a successful HTTP response, typically '200 OK'.

If the HTTP response is not a successful one, for example '500 Internal Server Error', SmarterPay Cloud will retry sending the webhook at a later time.

SmarterPay will attemp to send the Webhook 6 times, with an increasing interval between retries.

Only after the 6th, unsuccessful, retry attempt is the Webhook status marked as failed.
If a profile has been set for “Webhook Error Internal Profile”, in the Subscription settings, an email will be sent out with notification of the failure.