Webhooks

Troubleshooting

Troubleshoot common problems with the 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.

Troubleshoot common problems with the Webhooks API.

If a webhook endpoint returns an error message instead of the values you expect, check this topic 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 hours. After 72 hours, the notification is discarded and not sent again.

Solution Permalink Get a link to this section

Verify that your application is responding to notification deliveries in the required time period with an HTTP 2xx response code. For more information, see Features of Square Webhooks.

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 identifies your application. You might have configured one v1 webhook subscription and one v2 webhook subscription or configured two v2 webhook subscriptions to be sent to a common webhook listener address. If so, 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 notification URL 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.