Webhooks

Schema

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