Get a reference id in webhook payload

Hello. when i create a checkout, i can set a reference_id field in the body of the request. my problem is that i can’t see this reference_id field in the webhook payload, so it is hard to connect the webhook event to the correct checkout. i know i can use the generated order_id to connect the entities, but this is a bit problematic for us, because we have a distributed architecture, and some of our customers has their own server, and since the webhook is defined globally (and not per call) we have a situation where the webhook call is received by a different server than the server that initiated the checkout call, and without a reference_id it is a bit complicated to know which server initiated the call and complete the transaction.

So my question is - is there a way to add a reference_id or any other custom data to the checkout that will appear in the webhook payload?


Hi @zemer welcome to the forums!

Unfortunately I don’t think this is possible directly. Since the reference_id would live on the Order, but the order webhook doesn’t get fired with a CreateCheckout call (because it only fires with a direct CreateOrder call), it wouldn’t show up in the webhook. However, you should be able to retrieve the order, using BatchRetrieveOrders, to quickly look up the reference_id associated with the checkout.

Hi @sjosey and thank you for your response.
I’m sorry to hear that there is no way to get a reference id on the webhook. it is a bit strange, because this is the place where the reference id is the most useful, this is the place where i need to connect between the data in our db and the data received from Square. From our experience with other services (payments and other) there is always a way to get the equivalent of reference id in a webhook.

Unfortunately we cannot use an api call to get this reference id, let me explain again the problem -
we have different customers - each has it’s own context, and some are on dedicated servers. when i create a checkout i create it from one of those servers. but since i cannot have a different webhook to different checkouts (as a side note i can say that if i could set the webhook address in the api call it would also solve my problem) - i need to have a single “hub” server that will transfer the webhook data to the correct customer system. but without a reference id i cannot know which customer this webhook belongs to, and i can’t call the api because without knowing who is the customer i can’t know which access token to use.

i can of course work around this problem by maintaining a db of orders in the hub server, and updating it with calls from the customers servers, but this just seem like unnecessary work, which would have been avoided if i had a reference id in the webhook… which is a pitty.

Maybe you can consider adding this reference id to the payload sometime in the future…

anyway thank you again for you answer

Most payment gateways have ways of receiving custom variables in the callback payload, so this is poor from Square. I also hope it can be added in the future.

For now, it can be accomplished with the custom callback url, which does pass the custom var back in the url so I can attach the order id to the sale at that point. Example with the API:


On the redirect, assign the trans ID to the ref ID, then get the ‘order_id’ in the payload.