Webhooks are used to notify your application of changes to the status of Agreements, Payment Requests, Credits and Debits, etc as they are processed through the system.
By subscribing to our webhook events you can monitor the status of each transaction, and then trigger the appropriate next steps. Please refer to the webhook developer documentation for information on handling webhooks securely.
We support two types of webhooks
These webhooks are managed by the owner of the Split account and only report on events relating to the Split account.
To create an Owner webhook:
- Click on Webhooks from the top-left drop-down menu
- Click on the green + Webhook button found on the top right of the screen
These webhooks are managed by the Split OAuth2 application owner and will report on events relating to any authorised Split account (limited by scope)
To create an Application webhook:
- Click on Your applications from the top-left drop-down menu
- Click on one of your application, then click on the green + Webhook button
Webhook Event Payload
Each webhook event contains data relating to the event type. For example, when you receive an Agreement event, the payload will contain data relating to that agreement.
The webhook payload will also include metadata where available.
The best way to see example payloads for each type of webhook event is to try them out in the developer sandbox by creating a webhook and subscribing to all of the events.
Note that the payload for a single webhook event contains an array that may hold more than one transaction, so you'll need to loop through them all.
If your application is not ready to receive webhooks but you want a quick way to see the events in action, you can use https:/webhook.site to quickly create a URL that you can use as the webhook URL when settings up webhooks in Split. Alternatively, you can also use https://ngrok.com/ to allow webhook events to be posted to your local machine.
Once you have subscribed to all the events, you can try creating an Agreement, Payment Request or Payment in the sandbox. You can then see the events that have been sent to the configured webhook URL under the Deliveries heading on the webhook detailed page.
Knowing when a credit to your account has cleared
Transactions always have two parts, a debit and a credit. After using a Payment Request to get paid, your application can be notified when the debit from the debtor's account has cleared by subscribing to the Creditor Debit cleared event.
Note: To help understand the creditor debit event, think the creditor initiated debit event. Please refer to this article for more information.
Once the creditor debit has cleared, you can be notified when the credit to your account has cleared by subscribing to the Credit Cleared event.
The normal lifecycle of the creditor debit and credit events is shown below, and you can also subscribe to these events to keep your system updated.
- Creditor debit matured
- Creditor debit processing
- Creditor debit clearing
- Creditor debit cleared
- Credit matured
- Credit processing
- Credit clearing
- Credit cleared
Handling transaction failures
Transactions can fail for a number of reasons. The failure states include
prefailed . Subscribe to these webhook events to notify your system of transaction failures. For more information on all the status values, please refer to the transaction lifecycle developer documentation.