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.
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
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
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 treats2xx 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.