Hello!
I am trying to build a marketplace application for sellers. Is there a way to configure webhooks such that applications can listen to events occurring in seller accounts?
If two seller accounts have authorized my application for “PAYMENTS_READ”, my application should automatically receive every new payment that gets created in both seller accounts. Is this possible?
Thank you!
I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:
Refunds API Webhooks
Handle Bookings Webhook Events
Square Developer
If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.
Yes, it is possible to configure webhooks to listen to events occurring in seller accounts. The Payments API supports webhook events that notify you when a payment is created or updated. These notifications are sent on payment events for your seller, regardless of which Square product or Square API application the seller used for the payment activity.
You can set up a webhook subscription for all payment events. When a payment is created or updated in any of the seller accounts that have authorized your application, your application will receive a webhook event notification.
The Payments API uses these webhook events:
You can see these webhook events in real time on the Webhook logs page in the Developer Dashboard.
This answer was reviewed by @Bryan-Square.
Thank you. Can you please review the steps I have tried so far and let me know what I doing wrong.
const scopes = [
"PAYMENTS_WRITE",
"CUSTOMERS_WRITE",
"PAYMENTS_READ",
"ORDERS_READ"
];
I can confirm that the application is now listed in the App Integrations page within the Seller account.
5. I used the authorization code to receive an OAuth token and a refresh token for the Seller account
6. I created and deleted a customer in the Seller account but I have not received any events so far. Neither at the webhook URL or in the webhook logs for the application within the Platform account.
Thank you!
That’s because you don’t have CUSTOMERS_READ permissions. 
Thank you @Bryan-Square.
Hey @Bryan-Square. Quick follow up - Is there a way to manage webhook subscriptions such that I can configure different webhook endpoints for events different authorized sellers. Or can we only configure one endpoint that receives all webhook notifications for all events across all authorized sellers?
Thanks!
Currently with our webhooks you’ll receive events from all authorized sellers. There isn’t a way to filter it by merchant on the Square side.
Thank you. I understand that the filtering design and logic are left to the application.
Besides using a single URL, what solutions do apps have to divide and conquer webhook traffic? Particularly when they scale and have a large number of merchants sending in billions of requests. Do we create multiple apps in our account and split merchant traffic between them? Are there any limitations to this?
You can have more then one URL receiving webhook events to split traffic when scaling.
Thanks Bryan
I see that we can configure more then one URL receiving webhook events but wouldn’t that only work for scaling when you want to split traffic based on event type?
Let’s say we have 10000 merchants and they’re all sending events to our account. Multiple URLs can be used like following -
But in the use case where you want the same type of events (lets say payments) but across all the 10000 merchants, I am not sure if multiple URLs will work, right?
I also realize that we are potentially venturing into the territory of “that’s not Square’s problem” and we need to figure out how to scale and manage a high volume of events. Just want to see if there’s anything before going down the wrong path as it can be very expensive.
We have some very very large seller application with more then 10,000 connected sellers using webhooks and they’re working just fine.
It does depend a bit on how many sales per hour the end locations will do on average. Some random thoughts in a poorly organized order follow.
Combining your and Bryan’s suggestions, you have the ability to segment webhook traffic using one or both of these:
I’m not sure what your eventual aim here is, but just in terms of receiving webhook data, you might drop it into some form of queuing system (Redis, AWS SQS etc). Received events could be re-posted to the appropriate end URL (effectively forwarding/proxying the event) which could then do whatever you need.
You should fairly easily be able to handle 500 - 1000 webhook hits per second from the queue. on one of your servers. You do this by writing a minimal handler that doesn’t load anything extraneous to the processing task. Probably the most intensive part is the re-posting part and that’s where you’d want to do some good testing to check how many simultaneous outgoing POSTs you can have active per second, and how long they take.
You also need to expect that occasionally webhook hits will be lost, even if that’s very rare, and you can use the API to see what you missed by doing time-based searches. This would act to catch the data from missed events which you’d then construct into the JSON POST data to forward to your end servers.
If you build queue readers which pull events from the queue and process them, should then be fairly simple to ramp the number of independent queue readers up and down as needed to cope with load.
This would probably work pretty well even without a queuing system provided you have some form of load balancing. The virtue of a queuing system is that it makes it less likely you’ll lose packets when the load gets high.
A typical payment transaction will post about 5-7 progressive webhook hits over about 3-10 seconds although only the last one is final data, so you’d need to expect that. I think the others only post one event but you’d need to confirm that.
Thank you Brian. This is helpful and you’re right, this is doable but wanted to double check if Square had anything out of the box before we started implementing our back-end logic.