Webhooks

Webhooks are a convenient approach to notify an application about relevant events that have taken place within another application.

The event is similar to one in real-life, where you’re awaiting your favourite item to restock in a shop and ask a representative to notify you once it’s back. In this scenario, SumUp plays the role of the shop, the representative is the SumUp APIs and the update seeker is your application.

Events

At this time our system only allows you to get notified about a status change for a checkout. To subscribe to an event, specify a return_url parameter upon checkout creation.

New events may be introduced at any time, without prior notice. Your application has to be able to cope with such. Our recommendation would be to silently ignore unknown events.

Handling a webhook

Webhooks are delivered in the form of a HTTP POST request, to which your application should reply to as soon as possible. If the response takes longer, our system accepts this as a failed notification and retries it.

Your application should return a valid, empty response with any 2xx status code. Any response other than a 2xx is treated as erroneous.

Here's a sample of the webhook payload:

{
  "event_type": "CHECKOUT_STATUS_CHANGED",
  "id": "id-of-the-changed-checkout"
}

Retries

When an erroneous response is received, a webhook delivery is retried with the following delays:

• 1 minute
• 5 minutes
• 20 minutes
• 2 hours