# Webhooks

## Schema

```javascript
webhooks
  - id: UUID
  - url: string
  - enabled: boolean
  - createdById: UUID
  - name: string
  - secret: BYTEA (Encrypted string)
  - events: string[]
  - createdAt: Date
  - updatedAt: Date

webhook_deliveries
  - id: UUID
  - webhookId: UUID
  - statusCode: number
  - requestBody: JSONB
  - requestHeaders: string
  - responseBody: string
  - responseHeaders: string
  - createdAt: Date
```


## Endpoints

Standard crud-ish API endpoints for this one. Note we’ll also need policies and presenters for these. Webhooks will be managed by admins only at this time.

#### /webhooks.create

`webhookCreator` command. Don’t forget to add `transaction` as an argument, all new commands should accept a transaction and pass to internal database operations.

#### /webhooks.info

#### /webhooks.list

paginated

#### /webhooks.deliveries

paginated list of deliveries for an individual webhook

#### /webhooks.delete

`webhookDestroyer` command. Don’t forget to add `transaction` as an argument, all new commands should accept a transaction and pass to internal database operations.

## WebhookProcessor

New `WebhookProcessor` consumes all events (`[“*”]`), finds enabled webhooks for event `teamId`, presents the data for the relevant entity and sends to the registered webhook url.

Ideally we’d include a header that contains a signature based on the secret provided on webhook setup that the receiver can use to verify the source of the webhook, but this could come in a second pass.

All responses (success and failure) are recorded as `WebhookDelivery` rows

If the webhook fails then we check the last 25 delivery attempts, if all failed then we automatically disable the webhook and send a notification email to the creator. 

## CleanupWebhookDeliveriesTask

New task triggered from `cron.daily` endpoint that will permanently destroy webhook deliveries older than a week. This seems like a reasonable balance of retention for debugging purposes vs database bloat, but the retention time could be tweaked later.

## Interface

New screen under **Settings → Details** to list and create webhooks, this should be similar in form to API Keys and only be accessible to admins.

Creating a new webhook should happen in a modal, similar to creating an API Key.

You should be able to choose which events are sent, similar to GitHub – either an entire category like `documents`, or a specific event like `documents.update`.

Ideally this would use `react-hook-form` for form management. Although this hasn’t been used before I’ve been wanting to move new forms over to it.

Listing webhook deliveries here could be left out for first version.


 ![GitHub's event select UI](https://outline-production-attachments.s3-accelerate.amazonaws.com/uploads/292079f8-0319-4111-bb5b-315e8ae8f14e/0f9c0f87-8b80-4d3e-8663-5bfcc2470d82/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA4EOUDTOVUICLPZ4P%2F20260912%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260912T011500Z&X-Amz-Expires=86400&X-Amz-Signature=cf722d3f14726f57f02e95311197c8e9e0afc3d6ac700b05909834791f185413&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =832x588")