Setting up Webhooks
Your integration with topi is only considered fully functioning if you are listening for and responding to topi's webhooks. Webhooks are HTTP requests made from topi's server to yours, triggered whenever a significant event has occurred (e.g. when a customer has placed an order).
Manual URL configuration
When you have setup endpoint(s) on your server to listen to topi webhooks, please send that URL to your topi point of contact, who will then configure it on topi's backend. This one-off process remains manual on our side.
Now let's take a look at the topi webhooks that you'll need to listen for.
Offer webhooks
Whenever an offer status changes to "accepted", "declined", "pending_review", "voided", or "expired", topi will send a webhook to your configured URL.
You can see when these events are triggered and what these statuses mean in Offer states.
For details of the webhook payload, please refer to the Offer API reference.
Order webhooks
Whenever an Order status changes to "created", "partially_fulfilled", "completed", "cancelled", or "rejected", topi will send a webhook to your configured URL.
You can see when these events are triggered and what these statuses mean in Order states.
For details of the webhook payload, please refer to the Order API reference.
Frequently Asked Questions (FAQs)
Can I trigger a webhook to be re-sent?
Sometimes you might notice in your logs that some webhooks were received but your process failed with an Internal Server Error. Or your webhooks server might have had an outage and you require a couple of webhooks within a specified timeframe to be re-sent from topi.
As we do not yet have a developer portal that allows you to do this yourself, please reach out to your topi point of contact with details about the webhook that you'd like to be re-triggered.
Which IP Addresses are the Webhooks sent from?
You can find the full list of relevant IP addresses here.
Please allow-list the IP addresses stated in their docs to ensure smooth delivery of webhooks.
Allow-listing only the IPv4 addresses is enough. You don't need to allow-list the IPv6 address if that is not feasible on your end.