All Collections
New Zealand Help Articles
[NZ] How to use webhooks with your API integration
[NZ] How to use webhooks with your API integration
Updated over a week ago

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 Zepto account and only report on events relating to the Zepto account.

To create an Owner webhook:

  1. Once you're logged into your Zepto account, click on your name at the top left of the interface

  2. Within the drop-down menu displayed, click Webhooks

  3. Click on the green + Webhook button found on the top right of the screen


These webhooks are managed by the Zepto OAuth2 application owner and will report on events relating to any authorised Zepto account (limited by scope)

To create an Application webhook:

  1. Once you're logged into your Zepto account, click on your name at the top left of the interface

  2. Within the drop-down menu displayed, click on Your applications

  3. Click on one of your applications, 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 the https:/ to quickly create a URL that you can use as the webhook URL when settings up webhooks in Zepto. Alternatively, you can also use 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 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.

  1. Creditor debit matured

  2. Creditor debit processing

  3. Creditor debit clearing

  4. Creditor debit cleared

  5. Credit matured

  6. Credit processing

  7. Credit clearing

  8. Credit cleared

Please also find an article attached here, that will help you understand the webhooks events you will receive for the types of the transaction.

If you would like to check the configuration of your webhooks or redeliver specific webhooks you can refer to our article attached here.

Handling transaction failures

Transactions can fail for a number of reasons. The failure states include rejected , returned , voided and 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.

Is Your Delivery Showing A Different State Than The Delivery Type?

When webhooks are sent, our system will populate the payload fields using the current state of the object that it relates to.

For a transaction that uses an NPP channel, it essentially clears straight away and the credit status moves to cleared very quickly. So, when the fields are populated for the debtor_credit.xxxx webhook notification, the current status of the credit is actually cleared which is what may be returned back to you.

Please be mindful that you would still receive a debtor_credit.cleared event.

Our Delivery Promises

  1. We only consider a webhook event delivery as failed if we don't receive any http response code (2xx, 4xx, 5xx, etc.)

  2. We will auto-retry failed deliveries every 5 minutes for 1 hour.

  3. Delivery order for webhook events is not guaranteed.

  4. We guarantee at least 1 delivery attempt.

Feel free to reach out if you have further questions by emailing us directly at or clicking on the blue bubble icon from the corner of the screen.

Did this answer your question?