Webhooks

Hyphen sends outbound webhooks when workflow, approval, document, and generation events occur.

Base URL used below: https://apisvr.tryhyphen.com

Registration API

Register per-org webhook targets with /webhooks:

bash
curl -X POST https://apisvr.tryhyphen.com/webhooks \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "document.uploaded",
    "url": "https://example.com/hyphen/webhooks",
    "secret": "whsec_abc123",
    "filter": {
      "tags": ["invoices"],
      "content_type": "text/csv"
    },
    "auto_payload": {
      "source": "hyphen"
    }
  }'

Supported registration endpoints:

  • POST /webhooks
  • GET /webhooks
  • GET /webhooks/:id
  • PATCH /webhooks/:id
  • DELETE /webhooks/:id

Current validation for registrations allows these events:

  • document.uploaded
  • document.version_created
  • document.deleted
  • document.expired

Note: runtime emits additional events too (listed below). If you need registration support for all emitted events, expand the event allow-list in the server validation schema.

Payload Envelope

Every delivery uses this envelope:

json
{
  "event": "document.uploaded",
  "timestamp": "2026-03-03T10:30:00.000Z",
  "payload": {
    "document_id": "doc_a1b2c3d4e5f6",
    "name": "Q4 Transactions",
    "content_type": "text/csv"
  }
}

Field meanings:

  • event: event name
  • timestamp: ISO timestamp at send time
  • payload: event-specific payload data

Signature Verification

If a secret is configured on the webhook target, Hyphen sends:

  • X-Hyphen-Signature: sha256=<hex-hmac>

HMAC algorithm: SHA-256 over the raw JSON body.

Runtime Event Names

Observed emitted events in current runtime:

  • workflow_run_started
  • workflow_run_completed
  • workflow_run_failed
  • pbot_approval_requested
  • pbot_approval_decided
  • document.uploaded
  • document.deleted
  • external_form_created
  • external_form_updated
  • external_form_deleted
  • external_form_submitted
  • workflow_creation_status
  • llm_generation_status
  • llm_key_missing

Retry Policy

Delivery behavior:

  • Success: any 2xx
  • Retryable HTTP: 429, 408, 5xx
  • Non-retryable HTTP: all other 4xx
  • Backoff: exponential (starting at 1 second)
  • Max attempts: 5
  • For 429, Retry-After is honored when larger than current delay

If all targets fail for an event, sender raises an error for that event path; webhook delivery still remains non-blocking for most request handlers.

Legacy Compatibility

Hyphen also supports a legacy org config key webhook_url and will deliver to it if set.

Use new /webhooks registrations for event-level routing, filtering, activation state, and signing.