Setting up a webhook relay
A relay guarantees you receive every webhook event, even if your backend is down.
TalkJS tries to deliver each event up to three times before giving up, but if your backend is offline for a longer period due to updates or maintenance, it can miss webhook events. Running a separate webhook service guarantees you receive every webhook even if your backend is offline for longer periods.
This guide uses self-hosted Convoy Community on a separate VM. Hosted options include Convoy Cloud and Hookdeck.
Convoy receives events from TalkJS, saves them in PostgreSQL, and forwards them to your backend. Stored events remain available after delivery so you can inspect them or replay them later.
Follow Convoy's Docker installation guide to run Convoy Community on a VM separate from your application server. This lets Convoy keep receiving and storing events while your application server is offline for updates or maintenance. Run Convoy's PostgreSQL database and Redis queue on that VM too, with persistent data volumes.
Incoming events and pending deliveries pass through Convoy's Redis queue. Enable Redis append-only persistence so queued work survives relay restarts, and use noeviction so Redis doesn't discard it when it runs out of memory. In the installation's Compose file, set the Redis service's command to:
command: ["redis-server", "--appendonly", "yes", "--appendfsync", "always", "--maxmemory-policy", "noeviction"]Keep Redis's data volume mounted at /data.
Give Convoy a public HTTPS address, then configure it in the Convoy dashboard:
- Create an Incoming Webhooks project.
- Under Sources → Create source, choose Custom, name it TalkJS, and set Source verification to None.
- Under Endpoints, add the public URL of your application's webhook endpoint.
- Under Subscriptions → Create Subscription, connect the TalkJS source to that endpoint using the default payload settings.
- Copy the source URL from Sources and use it as the webhook URL in the TalkJS dashboard, replacing the direct application URL.
Events now follow TalkJS → Convoy → your endpoint.
Convoy's built-in verifier doesn't support TalkJS's signature format, so this setup stores requests without checking their TalkJS signature. Convoy preserves the original body and signature headers, so your backend can verify the signature when it receives the event.
In Project Settings → Retry logic, set the retry window to cover the downtime you want to tolerate. For example, Linear time retry with Duration 60 seconds and Limit 1440 gives roughly a day of automatic retries.
The Community edition used here doesn't automatically expire saved events. They remain in PostgreSQL after delivery or after retries run out, and you can inspect them in Events log. If you later enable a paid retention policy, keep events for longer than the retry window so you can investigate and replay failed deliveries.
If automatic retries run out, restore the endpoint and retry the failed deliveries from Event Deliveries. Repeated deliveries have the same TalkJS event ID. Use it to avoid processing the same event twice.
Stop your application's webhook server in a test environment, leaving Convoy running. Send another chat message. The event appears in Convoy and its delivery has status Retry, even though your app can't receive it yet.
Start the application server again. On the next attempt, Convoy delivers the queued event and the delivery changes to Success. You can use Events log to inspect the saved payload and Event Deliveries to inspect each attempt.