Learn about common issues developers encounter when implementing Square webhooks.
If you're encountering issues with webhooks, review the following for the most likely causes and solutions.
Square webhook notifications are typically sent within 60 seconds of the associated event. Applications must respond as soon as possible with an HTTP 2xx status code to acknowledge the successful delivery. Unsuccessful deliveries are retried for up to 48 hours. After 48 hours, the notification is discarded and not sent again.
Verify that your application is responding to notification deliveries in a timely manner with an HTTP 2xx status code.
Square webhook notifications require specific OAuth permissions. For example, you can only receive payment.created notifications if the seller grants the PAYMENTS_READ permission scope to your application.
Make sure that your application has the appropriate OAuth authorization for each seller. For more information, see OAuth API.
Did you know?
Webhook logs and the Events API can be useful for troubleshooting missed event notifications.
You've 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're matching the notification signature for one webhook event with the subscription signature of a different webhook.
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. You shouldn't define a V2 webhook subscription that emits events for the same API that you're already handling with a V1 webhook subscription. Instead, deprecate your V1 webhook subscription and replace it with a V2 subscription.