Webhooks is a mechanism that allows you to receive notifications about created events.

You simply create a page on your website and give us the URL to that page. Now, whenever a new event is created, we will call your page with information about that event.

Configuring webhooks

Webhooks can be configured in your account settings once you log in to your account. Each webhook URL can have one of two modes: live or test.

URLs configured for test mode will receive only events created in test mode, while URLs configured for live mode will receive only events created in live mode.

Receiving a webhook request

When a new event is created, we will POST the URL to each configured webhook. Event data are encoded as JSON and are sent in the request body. For each webhook, URL events are always delivered in the order they were created.

Remember - with webhooks, it is your server that is receiving webhook requests.

For security reasons, you should only use the event identifier from the webhook request and obtain the remaining data by making a direct request to the Shift4 API (see retrieving an event).

To protect your business from replay attacks, it is advised to record which events were processed and never process the same event twice.

Responding to webhook request

When the webhook request has been processed successfully, the returned status code must be a 200 HTTP status code. Any other return code is ignored.

If the webhook returns a status code other than 200, it is assumed that the requested delivery failed. Failed webhook requests are resent with an increasing delay between each attempt.

It is important to note that when event delivery fails for a given webhook URL, then delivery of all other events for that webhook URL will be blocked until that failed delivery is successfully retried.

That's because events are always delivered in the order they were created - so if one event fails to be delivered, we can't send any other events as this would result in out-of-order delivery.