Skip to main content

Use webhooks to get real-time updates

Listen for events on your application so your integration can automatically trigger reactions.

The Checkout API uses webhooks to notify your application when an event happens. Webhooks are particularly useful because allow you to automate custom backend actions in response to the transitions that happen in a payment flow.

What are webhooks​

A webhook enables us to push real-time notifications to your app. iCliGo uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems. To learn more, see iCliGo webhook events overview.

Steps to receive webhooks​

You can start receiving event notifications in your app using the steps in this section:

  1. Identify the events you want to monitor and the event payloads to parse.
  2. Create a webhook endpoint as an HTTPS endpoint (URL) on your server.
  3. Handle requests from the Checkout API by parsing each event object and returning 2xx response status codes.
  4. Send your publicly accessible HTTPS URL in the create Chechout Session requests.

What is a webhook endpoint​

Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTP or HTTPS endpoint on your server with a URL. If you’re still developing your endpoint on your local machine, it can be HTTP. After it’s publicly accessible, it must be HTTPS. You can use one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

Reciving events with webhook endpoint​

Types of events​

This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.

You'll notice that these events follow a pattern: checkout.session.event. Our goal is to design a consistent system that makes things easier to anticipate and code against.

Event​

checkout.session.authorized data.object is a checkout session
Occurs when a payment intent is authorized.
checkout.session.rejected data.object is a checkout session
Occurs when a payment intent is rejected.
checkout.session.paid data.object is a checkout session
Occurs when a payment intent succeeds capturing the amount.
checkout.session.unpaid data.object is a checkout session
Occurs when a payment intent fails to capture the amount.
checkout.session.completed data.object is a checkout session
Occurs when a Checkout Session has been successfully completed.
checkout.session.expired data.object is a checkout session
Occurs when a Checkout Session is expired.