Webhooks

Fyren can send real-time notifications to external services via webhooks. Each webhook is configured with a type, URL, and notification preferences.

Webhook Types

Slack

Sends formatted messages using Slack's incoming webhook format with color-coded severity indicators and structured attachments.

{
  "name": "Engineering Alerts",
  "url": "https://hooks.slack.com/services/T.../B.../xxx",
  "type": "slack"
}

Setup: In Slack, go to Apps > Incoming Webhooks > Add to Slack, choose a channel, and copy the webhook URL.

Discord

Sends formatted messages using Discord's webhook embed format with severity colors and structured fields.

{
  "name": "Status Updates",
  "url": "https://discord.com/api/webhooks/123/abc",
  "type": "discord"
}

Setup: In Discord, go to Server Settings > Integrations > Webhooks > New Webhook, choose a channel, and copy the URL.

Microsoft Teams

Sends formatted messages using the Microsoft Teams card format.

{
  "name": "Ops Channel",
  "url": "https://outlook.office.com/webhook/...",
  "type": "teams"
}

Setup: In Teams, go to the channel's Connectors > Incoming Webhook, configure a name and icon, and copy the URL.

Generic (JSON)

Sends a JSON payload to any URL. Supports HMAC signing for request verification.

{
  "name": "Custom Integration",
  "url": "https://api.example.com/status-webhook",
  "type": "generic"
}

Generic webhooks automatically receive a secret (32 random bytes, hex-encoded) at creation time. Each request includes an X-Fyren-Signature header:

X-Fyren-Signature: sha256=<HMAC-SHA256 hex digest>

The HMAC is computed over the request body using the webhook's secret. Verify it on your server to confirm the request came from Fyren.

Payload Format

{
  "event": "incident.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization": {
    "name": "Acme Corp",
    "url": "https://status.example.com"
  },
  "data": {
    "id": "abc123",
    "title": "API Latency Issues",
    "status": "investigating",
    "severity": "major"
  }
}

Notification Preferences

Each webhook has toggles for the types of events it receives:

Preference	Events
`notifyOnIncident`	`incident.created`, `incident.updated`, `incident.resolved`
`notifyOnMaintenance`	`maintenance.scheduled`, `maintenance.started`, `maintenance.completed`
`notifyOnComponentChange`	`component.status_changed`

Component Filtering

Webhooks support component-level filtering via the componentIds field. When set, the webhook only fires for events related to those specific components. When null, it fires for all events.

Testing

Send a test notification to verify your webhook is configured correctly:

POST /api/v1/admin/webhooks/:id/test

This sends a sample payload to the webhook URL and reports whether the delivery succeeded.

Enable / Disable

Toggle a webhook without deleting it:

PATCH /api/v1/admin/webhooks/:id/toggle

Retry Logic

Failed webhook deliveries are retried up to 3 times with exponential backoff (starting at 5 seconds). The webhook tracks consecutiveFailures and lastError for monitoring delivery health.

API Reference

See Admin Endpoints — Webhooks for the full API.

On this page