Webhook Destinations

Webhook destinations let your organization receive HTTP POST notifications when failures occur in Semaphor. Route these to incident management tools (PagerDuty, OpsGenie), messaging platforms (Slack or Teams via middleware), or custom logging endpoints.

Setting Up a Webhook

1. Navigate to Organization Settings.
2. Scroll to the Telemetry Webhook section.
3. Enter a webhook URL. The URL must use HTTPS.
4. Toggle the status to Active.
5. (Optional) Enter a Signing Secret for HMAC payload verification.
6. Open the Events dropdown and select which event types to receive.
7. Click Save Settings.

Event Subscriptions

By default, all nine event types are subscribed. Use the Events dropdown to narrow which types your endpoint receives.

At least one event type must remain selected. See Event Reference for full payload details.

Signing Secret and Payload Verification

Setting a Signing Secret

When you provide a signing secret, Semaphor signs every outgoing payload with HMAC-SHA256. The signature is included in the X-Semaphor-Signature header as sha256=<hex_digest>.

Verifying Signatures

To verify a webhook payload, compute the HMAC-SHA256 of the raw request body using your shared secret and compare the result to the X-Semaphor-Signature header value.

import crypto from 'crypto';

function verifySignature(body: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return signature === `sha256=${expected}`;
}

// In your webhook handler:
const signature = req.headers['x-semaphor-signature'];
const isValid = verifySignature(rawBody, signature, SIGNING_SECRET);

import hashlib, hmac

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return signature == f"sha256={expected}"

Always verify against the raw request body, not a re-serialized version. Re-serialization can change key ordering or whitespace, which invalidates the signature.

Testing Your Webhook

Click the Test button in the Telemetry Webhook settings to send a webhook_test event to your endpoint. The test uses the current form values (URL and signing secret), not the last saved configuration. This lets you verify a new URL before saving.

A successful test confirms URL reachability, TLS handshake, and signature verification (if a secret is set). If you don't have an endpoint ready yet, you can use webhook.site to generate a temporary URL and inspect incoming payloads.

Sample test event payload:

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "webhook_test",
  "occurred_at": "2025-06-15T14:32:08.491Z",
  "status": "test",
  "category": "webhook",
  "component": "telemetry-webhook-delivery",
  "message": "This is a test event from Semaphor.",
  "org_id": "org_abc123",
  "actor_type": "org_user",
  "actor_id": "usr_def456",
  "org_user_id": "usr_def456",
  "operation": "webhook_test",
  "stage": "webhook_test",
  "error_code": "test_event",
  "error_message": "This is a test event sent from the telemetry settings page.",
  "error_details": "{\"destinationId\":\"dest_ghi789\",\"destinationUrl\":\"https://example.com/webhooks\"}"
}

Delivery Behavior

Monitoring Destination Health

Each destination record tracks two health indicators:

• lastError -- The error message from the most recent delivery failure.
• lastFailureAt -- The timestamp of the most recent delivery failure.

Both fields are cleared on the next successful delivery. If lastError persists, your endpoint is consistently unreachable or returning non-2xx responses. These values are visible in the organization settings UI.

Troubleshooting