Docs

Webhooks

Webhook contacts let Watchman send HTTP requests to your systems when agents detect important events. Use them to fan out alerts into chat tools, incident systems, or custom pipelines.

Configure Contacts Read Contacts docs

What are webhook contacts?

A webhook contact is an HTTP endpoint that Watchman calls when an agent generates an alert. Instead of a human receiving an email or SMS, your service receives a structured request and can automate its own follow‑up actions.

Useful for Slack/Teams bots, incident platforms, ticketing tools, or internal services.
Configured per contact in the Directory, then attached to agents like any other channel.
Supports custom HTTP methods, headers, and bearer token authentication.

Configure a webhook on a contact

Go to Directory and create or edit a contact.
Enable the Webhook channel.
Set the Webhook URL — typically an HTTPS endpoint owned by your application.
Choose the HTTP Method (POST, PUT, or PATCH). POST is recommended for most integrations.
Optionally add JSON Headers and select an Auth Type (none or bearer).
If using bearer auth, set a bearer token that your service will validate.
Save the contact and attach it to one or more agents.

Token handling

For security, saved bearer tokens are not shown again in the UI. You can set or rotate the token, but you won't see the existing value after saving.

What your endpoint receives

When an alert is delivered via webhook, Watchman sends an HTTP request to your endpoint with a JSON body describing the alert and related metadata (time, stream, agent, and a textual description of what happened). The exact payload can evolve over time, so your integration should be tolerant of additional fields.

Read the request body as JSON in your framework of choice.
Log the full payload when you're building or debugging an integration.
Use the configured headers and bearer token to authenticate requests inside your application or gateway.

Security best practices

Prefer HTTPS URLs so alert payloads are encrypted in transit.
Use bearer auth or a gateway that validates a shared secret before accepting the request.
Restrict who can call the endpoint (IP allowlists, WAF rules, or API gateways) where possible.
Rotate bearer tokens periodically and update the token in your contact configuration in the Directory.

Production endpoints

Start with a staging endpoint when first wiring up webhooks. Once you're confident in the integration, point a dedicated production endpoint at your alert handling service.

Handling failures

Your endpoint should be resilient to duplicate deliveries and temporary failures. It's a good idea to make your alert handler idempotent and to log errors with enough context to diagnose issues.

Return a 2xx status code when you successfully process an alert.
Include internal correlation IDs in your logs to trace requests end‑to‑end.
If you change your webhook URL, update the corresponding contact in the Directory so future alerts go to the new endpoint.