Docs

Herald webhooks

Herald webhooks

Hosted inbound endpoints when you don't have your own Discord, Slack, or external webhook URL.

What are Herald webhooks?

Herald webhooks are inbound URLs that Herald hosts for you. POST JSON from anywhere — CI/CD, Zapier, a script, or a custom tool — and the payload is stored in your workspace Inbox. No Discord or Slack URL required.

Outbound vs inbound: Custom tools send HTTP out from Herald. Herald webhooks receive HTTP in to Herald.

Creating a webhook

  1. Go to Webhooks in the workspace sidebar
  2. Click Create webhook
  3. Name it (e.g. "CI deploy events")
  4. Copy the inbound URL and signing secret (shown once)

Inbound URL format:

https://herald.services/api/hooks/{workspaceId}/{hookId}

Copy the exact URL from the dashboard when you create the webhook.

Sending events

POST JSON to your webhook URL:

curl -X POST "https://herald.services/api/hooks/WORKSPACE_ID/HOOK_ID" \
  -H "Content-Type: application/json" \
  -H "x-herald-secret: whsec_YOUR_SIGNING_SECRET" \
  -d '{"event":"deploy","status":"failed","message":"Build error"}'

Successful requests return 202 with eventId and optional normalized fields.

Signing secret

Each webhook gets an auto-generated secret (whsec_…). When signing is enabled, include it in the x-herald-secret header. The secret is encrypted at rest and only shown once at creation — save it immediately.

Viewing events

  • Inbox — browse recent payloads in the dashboard
  • MCP tools — agents can call list_recent_events and get_event after Connect IDE

Use with custom tools & MCP

Point a custom HTTP tool at your Herald webhook URL so agents can trigger inbound events. Or POST directly from external systems and let agents read events via inbox MCP tools.

For chain-specific monitors (Alchemy, Tenderly), use Chain monitors instead — they include source-specific setup wizards and payload normalization.

Plan limits

Inbound hooks count toward your plan hook limit (Free: 2, Pro: 20, Platform: 100). Herald webhooks and chain monitor hooks share this quota.