UniLink Webhooks Overview (React to Events in Real Time)

UniLink webhooks send an HTTP POST to your server the moment an event happens — no polling required, no delays, no missed updates.

A webhook is an HTTP callback — UniLink calls your server rather than waiting for your server to call UniLink. When a contact signs up through your page, an order is placed, or a form is submitted, UniLink immediately sends a JSON payload to the URL you registered. Your application receives the event data in real time and can act on it instantly: send a confirmation email, update a CRM record, trigger a fulfillment workflow, or log analytics. This is fundamentally more efficient and reliable than polling the REST API for changes.

What Webhooks Do

Webhooks eliminate the need to periodically query UniLink endpoints to detect changes. Instead of asking "did anything happen since I last checked?" every minute, your server simply waits to be called. UniLink handles the event detection and delivery. Your endpoint receives a POST request with a JSON body describing exactly what happened, who it happened to, and when. You process it and return a 200 status code to acknowledge receipt — the whole exchange takes milliseconds.

Every webhook delivery includes a signature header, X-UniLink-Signature, that lets you verify the request genuinely came from UniLink and was not tampered with in transit. The signature is an HMAC-SHA256 hash of the raw request body, computed using a secret key UniLink generates when you register the endpoint. You compute the same hash on your side and compare — if they match, the payload is authentic. Never process a webhook payload without verifying its signature, especially for financial events like orders and payments.

UniLink's webhook delivery system is designed for reliability. If your endpoint is temporarily unavailable or returns a non-2xx status, UniLink retries the delivery up to 5 times with exponential backoff: first retry after 1 minute, then 5 minutes, then 30 minutes, then 2 hours, then 8 hours. If all retries fail, the delivery is marked as failed and appears in the webhook delivery log in the dashboard. You can manually replay failed deliveries from the dashboard for up to 72 hours after the original event.

How to Get Started

1. Build a publicly accessible HTTPS endpoint on your server that accepts POST requests. It must be reachable from the internet — localhost URLs do not work in production. For local development, use a tunneling tool like ngrok to expose your local server temporarily.
2. Log in to the UniLink dashboard at app.unilink.us and go to Settings → Webhooks.
3. Click Add Endpoint. Enter your HTTPS URL and select the event types you want to subscribe to. You can subscribe to all events or only specific ones to reduce noise.
4. Copy the signing secret displayed after saving. Store it securely as an environment variable — you will need it to verify incoming webhook signatures.
5. Test the integration by triggering an event in the dashboard (for example, submit a test form) and confirm your endpoint receives the payload and returns 200.

How to Use Webhooks

1. Return 200 immediately. Your endpoint should acknowledge receipt within 5 seconds by returning HTTP 200. Move any time-consuming processing (database writes, email sends, API calls) to a background queue so the response is fast and the webhook is not retried unnecessarily.
2. Verify the signature before processing. Compute HMAC-SHA256(rawBody, signingSecret), hex-encode the result, and compare it to the value in X-UniLink-Signature. Reject requests where they do not match — return 401.
3. Make your handler idempotent. UniLink may deliver the same event more than once due to retries. Use the event's unique id field to check whether you have already processed it before taking action (for example, store processed IDs in Redis with a short TTL).
4. Filter events by type. The payload always includes an event field (for example, order.created). Use a switch statement or event-type router to call the appropriate handler function and ignore event types your integration does not care about.
5. Monitor the delivery log. Go to Settings → Webhooks → [Your Endpoint] → Deliveries to review recent delivery attempts, see response times, and replay any failed deliveries manually.

Key Settings

Get the Most Out Of Webhooks

Use a message queue between your webhook endpoint and your processing logic. Your endpoint's only job is to validate the signature, push the payload onto a queue (Redis, RabbitMQ, SQS), and return 200. A separate worker process dequeues and processes the events. This decoupling means your endpoint never misses a delivery due to slow downstream operations, and you can scale the processing workers independently of the HTTP server.

Design your webhook handlers around the concept of eventual consistency. Events can occasionally arrive out of order, especially if your endpoint was temporarily unavailable and several retries stacked up. Build handlers that are tolerant of receiving a later event (like order.completed) before an earlier one (like order.created) — check the event timestamp and your database state before taking action rather than assuming events always arrive in sequence.

The delivery log in the dashboard is your best debugging tool. When a webhook is not being processed as expected, check the delivery log first. You can see the exact payload UniLink sent, the HTTP status your endpoint returned, and the response body. This is far faster than trying to reproduce the event manually. You can also replay any delivery from the log to re-test your handler against a real historical payload.

Register separate webhook endpoints for different concerns in your application. For example, one endpoint handles order events and writes to your fulfillment system, while another handles contact events and writes to your CRM. Keeping handlers focused makes them easier to maintain and debug, and if one handler has a bug, it does not affect the others.

Troubleshooting

• Register webhook endpoints in Settings → Webhooks → Add Endpoint and select which events to subscribe to.
• Always verify the X-UniLink-Signature HMAC header before processing any payload.
• Return HTTP 200 within 5 seconds — offload processing to a background queue to meet this deadline.
• Make handlers idempotent using the event id field to handle rare duplicate deliveries safely.
• Use the delivery log in the dashboard to debug failures and manually replay events within 72 hours.