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.

Connect the endpoint

Enter the complete HTTPS URL and choose Connect. Copy the signing secret immediately; it is displayed once.

Send a test event

In Test mode, choose Send test event. 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. After you rotate the signing secret with an overlap, the header carries one v1 per active secret, newest first: t=<timestamp>,v1=<new>,v1=<previous>. Accept the request when any v1 matches.

Event payload

Lynq currently sends one event type, payment_intent.succeeded.

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 with Now 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. Each delivery is listed in Dashboard → Webhooks, and the endpoint shows how many events failed in a row since the last success. After you fix the receiver, open a failed delivery and choose Resend to send the same event again, with the same event ID. Retries still stop 72 hours after the event was created, so a resent older event gets a single attempt.

Rotate a signing secret

When you rotate, choose how long Lynq keeps signing with the current secret as well: Now, 1 hour, 24 hours, or 7 days. During that overlap every delivery carries a signature from both secrets, so the receiver keeps verifying while you deploy the new one. With Now, the current secret stops at once and deliveries fail verification until the receiver has the new secret.

Rotate in Dashboard

In Webhooks, choose Rotate next to the signing secret, pick an overlap, and copy the newly displayed secret.

Update and deploy

Replace the receiver secret and deploy it before the overlap ends.

Verify

Send a Test mode event or watch the next live delivery.
Only the latest replaced secret is kept. Rotating again during an overlap ends the earlier one. See Errors and troubleshooting for investigating delivery failures.
Last modified on November 11, 2026