API Docs

Implementation Guide

What is a webhook?

A webhook is an outbound HTTP request we send to your system when something important happens (for example, an application status change). Instead of your service repeatedly polling our API, we push updates to an HTTPS endpoint you control.

In practice, a webhook is:

  • Method: POST
  • Content type: application/json
  • Body: an “event” payload describing what happened
  • Headers: metadata (including a signature so you can verify it’s genuinely from us)

Here is an example body:

{
    "token": "6G1c-4Auj-7aFm-1Wzm-6IU1-25PY-1YVz-8nGb",
    "status": "awaiting_confirmation"
}

Registering to receive webhooks

When you initialise a checkout journey using the Contract Create endpoint (POST /api/checkout/v1/init/), the request body supports a webhooks object (“webhooks block”) that lets you provide your webhook configuration as part of that initial request.

Why is it needed?

  • It lets you as the merchant know when an application's status has changed
  • Reduces (or potentially removes) the need to poll the status API for the status of the application

How to use it

  • In the JSON body you send to POST /api/checkout/v1/init/, include the webhooks object exactly as shown in the API reference (“webhooks” block).
  • Populate it with the URL(s) you want us to call when relevant events happen.
  • Make sure those URLs are HTTPS and reachable from the public internet.
  • Verify the integrity of the webhook value by:
🚧

It is important to validate that the webhook is sent from HeyLight and not a third party.

A typical webhook flow

  1. You create an endpoint on your server, e.g. https://merchant.example.com/webhooks/heylight or use one of our E-commerce plugins, which has webhook functionality enabled.
  2. You register that endpoint with us (so we know where to send events) via the Contract Create webhooks block.
  3. When an event occurs, we POST a JSON payload to your endpoint.
  4. Your endpoint:
    1. verifies the request (signature, etc.)
    2. processes the event
    3. returns a 2xx response quickly (and does any slower work asynchronously)

What your webhook endpoint must do

  1. Accept the request and read the raw body
  2. Verify the webhook signature (authenticity + integrity)
  3. Return a 200 quickly (ideally within 200ms)
  4. Be idempotent

You may receive the same event more than once (retries happen in real systems). Treat webhook processing as idempotent: deduplicate using the secret in the payload or another stable reference, and ensure reprocessing doesn’t cause double-shipments, double-refunds, etc.

Best practices for merchants

  • Use HTTPS and validate TLS.
  • Verify signatures on every webhook request (reject missing/invalid signatures with 401/403).
  • Log verification failures (but never log the signing secret).
  • Allow-list our IPs only if you have a stable allow-list from us; otherwise signature verification is the primary control.
  • Version your handler (e.g. /webhooks/heylight/v1) so you can evolve safely.
  • Monitor: track delivery success rates and response times.

Need help?

For any questions related to the integration, please contact:

Updated about 9 hours ago

Updated about 9 hours ago