Skip to main content
Webhooks notify your server after a payment succeeds. They are the authoritative signal for fulfilment because they do not depend on the customer’s browser staying open.

Create an endpoint in Dashboard

Build a public HTTPS route

Add a POST route that can read the raw request body. The endpoint must be reachable from the public internet over HTTPS and must not include credentials in its URL.

Select the environment

Open Dashboard → Webhooks in Test mode or Live mode. Each environment has one independent endpoint and signing secret.

Save the endpoint

Enter the complete HTTPS URL, enable it, and save. Copy the signing secret immediately; it is displayed once.

Send a test event

In Test mode, use the Dashboard test-event action. Confirm your route verifies the signature, records the event, and returns a successful response.
Store the signing secret in the same kind of server-side secret storage used for your secret API key. Do not put it in browser code.

Request contract

Lynq sends: The signature is HMAC-SHA256 over ${timestamp}.${rawBody}, using the endpoint signing secret.

Verify the signature

Verification must use the raw bytes or exact raw text received from Lynq. Parsing JSON and serializing it again can change whitespace or property formatting and invalidate the signature.
server/verify-lynq-webhook.ts
Reject missing, malformed, stale, or mismatched signatures before processing the payload.
Do not log the signing secret or include it in an error response. If it is exposed, rotate it in Dashboard and update the receiver immediately.

Process events exactly once

Webhook delivery is at least once: a successful payment event may be delivered more than once if a response is lost or a retry overlaps your processing. Make the event ID unique in your database.
server/handle-lynq-event.ts
Before marking the order paid, compare the webhook’s orderId, amount, and currency to your stored order. This protects against fulfilling the wrong order even when the event is validly signed. Return 2xx only after durable processing succeeds. If processing fails temporarily, return 5xx so Lynq retries. Avoid doing slow, unrelated work before acknowledging the event; enqueue downstream fulfilment after recording the event and payment state.

Delivery and retries

Lynq treats 2xx as delivered. Network failures, timeouts, 408, 429, and 5xx responses are retried with exponential backoff and jitter for up to 72 hours. Other 4xx responses are treated as non-retryable. The request timeout is 10 seconds. Keep the receiver path focused on verification and durable recording.

Rotate a signing secret

Rotation takes effect immediately and the previous secret cannot be restored. Update the receiving service with the new secret before the next event is delivered.

Prepare the receiver

Make sure you can update and redeploy its secret configuration immediately.

Rotate in Dashboard

Open the endpoint, choose Rotate signing secret, and copy the newly displayed secret.

Update and verify

Replace the receiver secret, deploy it, and send a Test mode event or monitor the next live delivery.
See Webhook event reference for the payload and Monitoring for investigating delivery failures.
Last modified on August 8, 2026