Request Handling

Description: Incoming webhook requests will include a JSON payload containing transaction information for:

• Type: Sale
• Type: Refund
• Type: Dispute

For an in-depth guide on Online Payments Webhooks, view the Online Payments Webhooks Guide.

---

Retries

A 2XX response is expected within 5 seconds for the webhook request to be successful. If the request fails, it will be retried up to 5 times using an exponential backoff strategy before it is considered failed.

Attempt	Time Interval
Attempt 1	4 Hours
Attempt 2	9 Hours
Attempt 3	16 Hours
Attempt 4	25 Hours
Attempt 5	36 Hours

Note: The retry attempts occur consecutively. For example, attempt one occurs 4 hours after the original webhook failed. Attempt two occurs 9 hours after attempt one and so on.

Security

Signature verification can be utilized to secure incoming webhook requests. A private key is shared with Shift4 when registering a webhook endpoint. This shared key is used to sign all webhook requests with a Shift4-Signature header, which can be used to ensure that the requests are not coming from a third party. A timestamp is also included to prevent replay attacks. For example:

timestamp=1669665867384,signature=8156881aa8c0b4f3657f89b99acd955fc4f9d96dcc47110d2136f6d07f5ff751

Verifying the Signature

To verify the signature, it first needs to be split on the comma character (,) in order to separate the timestamp and the signature. The resulting parts can then be split on the equal sign character (=) to get the values of both the timestamp and signature.

To generate a signature for comparison, you will take the timestamp value and concatenate it with the request body of the payload using the colon character as a separator (:). 

For example: 1669732695193:{body of event}

Note: Examples of the request body can be seen in the Examples article. 

Using the resulting string, you will then generate a hash using the HMAC-SHA256 cryptographic algorithm with the shared private key for the registered endpoint. If this hash matches the signature from the header, then the request is valid.

Preventing Replay Attacks

To mitigate replay attacks, the timestamp from the Shift4-Signature header can be used to ensure that requests are only valid within a predesignated time frame. Once the signature has been validated, a secondary check can be performed to ensure that the request happened within the allotted time. It is recommended to keep this time short (e.g., 1-5 minutes). Note that this timestamp parameter cannot change without invalidating the signature as it is used in the signing process.

Please proceed to the next article on this topic: Examples.