---
title: Webhook
icon: webhook
description: Set up, configure, and run the Reloop webhook microservice locally.
---
> For the complete documentation index, see [llms-docs.txt](/llms-docs.txt) or the site index [llms.txt](/llms.txt). Full docs corpus: [llms-full-docs.txt](/llms-full-docs.txt). Prefer markdown URLs (append `.md`) for agent consumption. Product skill: [skill.md](/skill.md).


Outbound event webhooks — subscription management, HMAC signing, delivery, and retries via BullMQ.

<Tip>
Run [`bun setup`](/docs/setup) once from the monorepo root. Env files come from `bun setup` / `bun env:setup`.
</Tip>


## Overview

| Property | Value |
| :--- | :--- |
| **Directory** | `apps/backend/webhook` |
| **Port** | `8013` |
| **Local URL** | [https://local.reloop.sh/api/webhook](https://local.reloop.sh/api/webhook) |
| **Swagger UI** | [https://local.reloop.sh/api/webhook/openapi](https://local.reloop.sh/api/webhook/openapi) |
| **Stack** | ElysiaJS · PostgreSQL · Redis · NATS · BullMQ |


## Quick start

```bash
bun be:webhook:dev
```

Or `bun backend:dev` / `bun dev`.


## Environment

`apps/backend/webhook/.env` — from `bun setup` / `bun env:setup`.

```bash
PG_URL=postgresql://reloop:reloop123@localhost:5432/reloop
REDIS_URL=redis://:reloop123@localhost:6379
WEBHOOK_ENCRYPTION_KEY=your-64-char-hex-key
PORT=8013
BASE_URL="https://local.reloop.sh"
NATS_URL=nats://localhost:4222
NODE_ENV=development
```

`WEBHOOK_ENCRYPTION_KEY` encrypts stored webhook signing secrets. If unset, secrets are stored in plaintext (local only).

| Variable | Required | Default |
| :--- | :--- | :--- |
| `PG_URL` | **YES** | `postgresql://...` |
| `REDIS_URL` | **YES** | `redis://...` |
| `WEBHOOK_ENCRYPTION_KEY` | Prod only | Dev key in `.env.dev` |
| `PORT` | **YES** | `8013` |
| `BASE_URL` | **YES** | `https://local.reloop.sh` |
| `NATS_URL` | **YES** | `nats://localhost:4222` |


## Commands

| Command | Description |
| :--- | :--- |
| `bun be:webhook:dev` | Start dev server with hot reloading |
| `bun run --filter=be-webhook build` | Compile production bundle |
| `bun run --filter=be-webhook start` | Run compiled production build |
| `bun run --filter=be-webhook check-types` | TypeScript type-check |


## Architecture

| Layer | Detail |
| :--- | :--- |
| **Control plane** | This service — CRUD endpoints, list deliveries, manual replay |
| **Dispatcher** | `be-workflow` NATS queue group `webhook-dispatcher` (email lifecycle + manual trigger) |
| **Delivery** | Dedicated BullMQ queue `webhook-delivery-queue`; signs with `Reloop-Signature` |
| **Retries** | Fixed 7-attempt schedule (5s → 5m → 30m → 2h → 5h → 10h) |
| **Helpers** | `@reloop/webhook-delivery` (envelope, HMAC, SSRF client) |
| **Schema** | `packages/db/src/schema/webhook.ts` |


## Next

<CardGroup cols={2}>
  <Card icon="rocket" title="Setup" href="/setup">
    One-command local bootstrap
  </Card>
  <Card icon="globe" title="Port reference" href="/setup/port">
    Gateway routes and ports
  </Card>
  <Card icon="mail-single" title="Mail" href="/setup/backend/mail">
    Source of delivery events
  </Card>
  <Card icon="logs" title="Logs" href="/setup/backend/logs">
    Analytics event sink
  </Card>
</CardGroup>