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