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

The headers we send are:

Here is an example body:

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

The body is sent on a single line, exactly as shown. If you verify the signature, do not reformat, reorder or re-serialise it — the signature is computed over these exact bytes.

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:
  • Verifying the signature OR
  • Making an outbound call to the status API to check the status of the Application from a trusted source.

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 on the token in the payload combined with the status, or on the Request-ID header, and ensure reprocessing doesn’t cause double-shipments, double-refunds, etc.

Signing keys and environments

Your webhook signing key is issued per destination URL and per environment. Your sandbox and production keys are different, unrelated values, even where both point at the same URL. A sandbox key will never verify a production webhook.

If you send both sandbox and production webhooks to the same endpoint, that endpoint will receive requests signed with two different keys, and nothing in the payload distinguishes them. Use a separate endpoint per environment, or accept a match against either key. See Verifying the signature for detail.

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:

• For HeyLight (Switzerland): [email protected]
• For HeyLight (Italia): [email protected]