Skip to main content

Webhooks

Stitch supports webhooks for different types of events: transactions, merchants, and terminals. Each webhook type can be sent to the same or different endpoints.

The webhook setup is not available through the API, but rather Stitch will set it up as part of an integration project.

Security​

You can secure your webhook with any static header that you prefer, for example:

  • my-header-name: <my header value>
  • Authorization: Basic Jsj3djJDJX3kKSDSK432kDKX

When Stitch is setting up the webhook configuration, you will need to provide the URL endpoint that will accept an HTTP POST and the header(s) you need Stitch to send on each webhook request.

Store-and-Forward​

Stitch will try to resubmit the webhook to your endpoint 5 times with a backoff delay of 30 seconds if a non-HTTP 200 response is received from your webhook. If we fail to deliver the webhook after the 5th attempt, the webhook payload will be stored in a dead-letter queue and Stitch will be notified of the failed delivery attempt.

The failed webhook payloads can then be manually resubmitted by Stitch when requested to do so.

Infinite Loop Prevention​

To prevent an infinite webhook scenario on merchant and terminal events, Stitch will only send out a webhook if we detect that a property on the entity was changed in the last 10 minutes by checking the SHA256 hash of the entity.

An infinite webhook scenario would occur when an API client consumer uses the Stitch API to update the merchant and the merchant webhook has been configured to send out webhooks for merchant events. The webhook consumer would receive the merchant webhook, update its own merchant record which then triggers an API update event to the Stitch API, which then again triggers a merchant webhook.

It is advised that webhook and API clients have similar measures in place.