Webhook Integration

Prerequisites

For this integration method, you will need to provide an endpoint to hook the user updates to, with the following specs.

• HTTPS enabled.
• POST enabled
• Max of 2048 characters url.
• Should expect a json payload:

  {
      // Your company id
      "company_id": string,
      // The id of the user whose data just been updated.
      "user_id": string,
      // A random id of this specific new data snapshot.
      "snapshot_id": string,
      // The timestamp of the user's last processed transaction.
      "last_transaction_timestamp": number,
  }

Overview

1. Once new data is available for a certain user, the system will call the webhook endpoint with the following payload:

   curl -XPOST 'https://api.somebusiness.com/webhook/url/xxxxxxxxxxxxxxxxxxxxxxxxxx' \
       -H "Content-type: application/json" \
       -d '{
           "company_id": string,
           "user_id": string,
           "snapshot_id": string,
           "last_transaction_timestamp": number,
       }'

2. At this step you probably need to fetch the new data.

3. The webhook response indicates the success or failure of the event handling.

Successful handling

If the webhook returns a 2xx response, the system will consider the event has been handled successfully and will not resend the event again.

Failure handling

If the webhook returns any response other than 2xx, our system will retry the call every 2 hours, if the request keeps failing after 96 hours the system will give up on the event and will disregard it.

Pro tips

tip

Every transaction will have a timestamp field indicating the time this transaction has happened in real-life, you can use the last timestamp you have with the /merchant/users/:user_id/transactions endpoint to get only the transactions After this timestamp.

tip

You can Optimize this flow by checking the last_transaction_timestamp against the last transaction timestamp for that specific user in your DB and see if you need to update anything.