Skip to main content

Setting up Webhooks

Important

Your integration with topi is only fully functioning if you listen for and respond to topi's webhooks. Webhooks are HTTP requests from topi's server to yours, triggered whenever a significant event occurs (for example, when a customer places an order). Your endpoint must respond with a 2XX status to acknowledge receipt.

Setting up your webhook endpoint is a one-time step. Once it is in place, topi sends you real-time updates as offers and orders change status, so you do not have to poll the API.

Register your endpoint​

When you have set up an endpoint on your server to receive topi webhooks, send that URL to your topi point of contact, who will configure it on topi's side. This one-time configuration is currently manual on our end.

Offer webhooks​

topi sends an offer webhook whenever an offer changes to one of these statuses:

  • offer.accepted
  • offer.declined
  • offer.pending_review
  • offer.voided
  • offer.expired

See Offer states for what each status means and when it occurs. For the payload, see the Offer API reference.

Order webhooks​

topi sends an order webhook for these events:

  • order.created - an offer was accepted and has become an order for you to fulfil.
  • order.canceled - the order was canceled (by topi or at the customer's request).
  • order.completed - all parts of the order have been fulfilled.

topi does not send webhooks for the other order statuses: acknowledged, confirmed, partially_fulfilled, and rejected. You move the order through those yourself by calling the API (acknowledging it, accepting it, shipping items, or rejecting it), so there is nothing for topi to notify you about. See Receiving and fulfilling orders for that flow, and the Order API reference for the webhook payload.

Frequently asked questions​

Can I trigger a webhook to be re-sent?​

Sometimes a webhook is received but your processing fails, or your endpoint has an outage and you need a few webhooks re-sent for a given timeframe. We do not yet have a self-service developer portal for this, so please reach out to your topi point of contact with the details of the webhook you want re-triggered.

Which IP addresses are webhooks sent from?​

topi delivers webhooks through Svix. You can find the full list of source IP addresses in the Svix documentation. Allow-listing the IPv4 addresses is enough; you do not need to allow-list the IPv6 address if that is not feasible on your end.