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 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 the successful delivery. Unsuccessful deliveries are retried for up to 72 hours. After 72 hours, the notification is discarded and not sent again.
Verify that your application is responding to notification deliveries in the required time period with an HTTP 2xx response code.
Square webhook notifications require OAuth authorizations. For example, your application receives a payment.created notification for a particular seller if it's authorized by that seller with a PAYMENTS_READ scope.
Make sure that your application has the appropriate OAuth authorizations for each seller.
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.