Webhooks and Events

About Webhooks

Our notifications are webhooks that allow our partner’s apps to stay in sync with Sniptech or User updates, and perform an action after a specific event occurs.

For example, a webhook can notify the app when a bank connection for a user has expired. The app can then action when this change occurs, e.g. notify the user, store it for reporting and analytical purposes.

This guide introduces how webhooks work, including how to setup a webhook for the app and manage webhooks.

To process notifications, a partner app needs to:

  1. Create a subscription with an endpoint on the server and (an) event(s) to be received using POST /subscriptions endpoint of the Webhook API;

  2. Accept notifications;

  3. Test and go live.

The Webhook API also allows you to manage your subscription(s) and secret(s) with the following operations:

  • Create a secret key.

  • Get a subscription by id.

  • Update subscription.

  • Delete subscription.

  • Update subscription status.

For more information, see https://developer.sniptech.com/api-details#api=sniptech-webhooks-api

Integration

Step 1 : Create subscription with an endpoint on the server and event(s) to be received

Notifications are sent as HTTP callbacks (webhooks) to an endpoint on the server. Sniptech recommends the partner to use HTTPS endpoints with TLSv1.2.

To receive notifications, you need a server that has:

  • An endpoint that can receive a JSON or an HTTP POST.

  • For test environments: an open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (443, 8443, or 8843) with TLSv1.2.

  • Bearer Authorization Token for scope webhook. Details for further accessing the Authorization framework can be found here: https://developer.sniptech.com/Authorization.

The server URL and events to be enabled have to be passed in the request of the POST /subscriptions endpoint.

Each webhook event includes a description of the webhook properties and an example payload. For more information, see "Partner Events“.

Step 2: Accept notifications

To ensure that partner’s server is properly accepting notifications, we require the partner to acknowledge every notification of any type with a response containing the body: isAcknowledged:true & timestamp:[date and time]

If we don't receive this response within 1 minute, for example, because the partner server is down, all notifications on the endpoint will be queued and retried. 
In total, two retries which are triggered in 15m (1s retry) and 60m (2d retry). If the last retry fails, notifications will no longer be sent and can not be retrieved.

When the partner server receives a notification:

  1. Verify the HMAC signature included in the notification. For more information, refer to Webhook Security .
    This is to confirm that the notification was sent by Sniptech, and was not modified during transmission. If the HMAC signature is not valid, we do not recommend acknowledging the notification.

  2. Store the notification in the database.

  3. Acknowledge the notification with HTTP 200 and isAcknowledged:true & timestamp:[date and time] in the response body.

  4. Apply the business logic.
    Sniptech recommends to acknowledge the notification before applying any business logic, because a breakage in the business logic could otherwise prevent important updates from reaching the system.

It’s possible to receive the same event multiple times, for this reason use eventId as idempotency key to prevent handling the same event more than once and acknowledge the request.

Step 3: Test and go live

Test

To test your notifications server and integration, Sniptech provides POST /events endpoint to simulate the trigger of the events on test and acceptance environments. You can use this endpoint to generate all supported event types.

Go live

  1. Follow the instructions in Step 1 to set up notifications.

  2. If you're verifying HMAC signatures, make sure that you use the HMAC key for your live environment, which should be different from the HMAC key from your test environment.