---
url: https://talkjs.com/docs/Guides/Webhook_Relay/
title: "Setting up a webhook relay | Guides | TalkJS Docs"
---

For AI agents: Find a documentation index at https://talkjs.com/llms.txt (full content at https://talkjs.com/llms-full.txt). Get a markdown version of any page by appending .md to its URL path.

# 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](https://www.getconvoy.io/) Community on a separate VM. Hosted options include [Convoy Cloud](https://www.getconvoy.io/pricing) and [Hookdeck](https://hookdeck.com/).

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.

## Run Convoy on a separate VM

Follow [Convoy's Docker installation guide](https://www.getconvoy.io/docs/deployment/install-convoy/docker) 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:

```yaml
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:

1.  Create an **Incoming Webhooks** project.
2.  Under **Sources → Create source**, choose **Custom**, name it **TalkJS**, and set **Source verification** to **None**.
3.  Under **Endpoints**, add the public URL of your application's webhook endpoint.
4.  Under **Subscriptions → Create Subscription**, connect the TalkJS source to that endpoint using the default payload settings.
5.  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](https://talkjs.com/docs/Features/Security/#verify-webhook-integrity) when it receives the event.

## Choose how long to keep retrying

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](https://www.getconvoy.io/docs/product-manual/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.

## Check recovery

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.
