Webhooks

Troubleshooting

Troubleshoot common problems with the Webhooks API.

Webhooks API

If a Webhhooks endpoint returns an error message instead of the values you expect, check here for the cause and most likely solution.

I did not receive my webhook notification
Permalink Get a link to this section

Likely Cause
Permalink Get a link to this section

Square Webhook notifications typically send within 60 seconds of the associated event. Applications must acknowledge the notification by responding within 10 seconds with an HTTP 2xx response code to acknowledge successful delivery. Unsuccessful deliveries are retried for up to 72 but after 72 hours have elapsed, the notification is discarded and will not be sent again.

Solution
Permalink Get a link to this section

Verify your application is responding to notification deliveries in the required time window with an HTTP 2xx response code. For more information, see the Webhooks guide.

I cannot validate a webhook notification against my webhook subscription
Permalink Get a link to this section

Likely Cause
Permalink Get a link to this section

You have defined more than one webhook subscription for the client ID that identifes your app. You may have configured a Webhooks v1 and Webhooks v2 subscription or 2 Webhooks v2 subscriptions to be sent to a common webhook listener address. If so, then you are matching the notification signature for one webhook event with the subscription signature of a different webhook.

Solution
Permalink Get a link to this section

Define a unique webhook listener for each subscription and then update each webhook subscription with the listern address intended to handle events on that subscription.

Did you know?

You should not define a v2 webhook subscription that emits events for the same API that you are already handling with a v1 webhook subscription. Instead, deprecate your v1 webhook subscription and replace it with a v2 subscription.