Webhook Duplicates

Structure

The structure of our webhooks can be divided into two basic parts:

1. Business data of the webhoook, e.g. invoice created, failed payment, etc.
2. Metadata about the webhook.

The business data will vary depending on the webhook event type. The metadata is information about the webhook attempt itself, and consists of the following fields:

• requestId : A unique identifier in version 4 UUID format representing our attempt to send you a webhook event. If the attempt fails we will retry, and the subsequent attempt will have the same requestId (See the section below on Scheduling and Retries for more information).
• merchantId : The merchant the event relates to.
• eventType : The event type you specified when registering the webhook.
• createdOn : The date and time the webhook notification was first created. This will stay the same across retries.

{
  "requestId": "db03cf0d-4fdb-481c-8fd5-3fc7b2f1df47",
  "merchantId": "e052abb1-f6ef-4ca5-a710-cde340841cd8",
  "eventType": "CUSTOMER_CREATE",
  "createdOn": "2019-01-30T22:40:21.221",
  "data": {
    "id": "1c786d20-4b16-4a4a-9595-bf50cfcff8bf",
    "number": "EZY1234",
    "referenceCode": "REF_123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "companyName": "Acme Inc",
    "mobilePhone": "1234",
    "homePhone": "5678",
    "createdOn": "2019-01-30T22:40:21.164",
    "address": "123 Road Street, Sydney NSW 2000"
  }
}

🚧

The requestId is particularly important and useful as it is the key to ensuring you don't consume duplicate webhooks.

Why would you receive a duplicate?
To explain this, you need to know how we schedule and retry your webhooks.

Scheduling and Retries

When you register a webhook for a given event type, you will receive a notification to your nominated URL as soon as the event occurs in Ezypay's system. In case the notification fails to send, we will retry it every 60 minutes, up to a maximum of 24 times.

What does 'failed' webhook mean in this context? Well, looking at it from another angle, a webhook 'succeeds' if we make an HTTP request to your nominated URL and get back an HTTP response in the 200-299 range. Therefore, a webhook attempt can fail if we send you a webhook and:

1. We don't get a response, i.e. the request times out.
2. We get back anything other than a response in the 200-299 range.

In the case of either type of error, we will mark the attempt as failed and try again later as per the retry schedule mentioned above.

Dealing with Duplicates

There is one situation in which you may receive duplicate webhook events: we send you a webhook, you process it, but don't send us an HTTP response in the 200-299 range. We will treat this as a failure and schedule a retry.

You can deal with duplicates on your end by looking at a webhook event's requestId property. A retry will have the same requestId, so if you encounter a webhook with a requestId that you have already processed you can safely ignore it. Please be sure to send an HTTP 200 response anyway so that we can mark it as successful and stop sending you retries.