Webhook Receivers

Overview

Not every service you depend on has a public status page. Webhook receivers let external services push status updates directly to Alert24 via HTTP POST requests. When Alert24 receives an update, it automatically changes your service status, updates your status page, tracks SLA, and notifies your team — just like a status page check would.

This is useful for:

• Services without status pages — Internal tools, smaller SaaS providers, or custom infrastructure
• Your own services — Push status from your CI/CD pipeline, health checks, or monitoring tools
• Alert24-powered status pages — If a service you depend on uses Alert24 for their status page, they can push updates directly to you

How It Works

1. Create a webhook receiver in Alert24, linked to one of your services
2. Get the unique URL — Alert24 generates a secure endpoint like https://alert24.net/api/webhooks/incoming/<token>
3. Configure the external service to POST JSON status updates to that URL
4. Alert24 processes the update — extracts the status, maps it to operational/degraded/down/maintenance, and updates your service

Setting Up a Webhook Receiver

Step 1: Create a Service

If you haven't already, create the service that will be updated by the webhook:

1. Go to Services > Add Service
2. Name it (e.g., "Pushmail Email Delivery")
3. Save

Step 2: Create the Webhook Receiver

1. Go to Settings > Webhook Receivers > Add Receiver
2. Give it a name (e.g., "Pushmail Status Updates")
3. Select the target service
4. Configure the status field path and mapping (see below)
5. Optionally set an HMAC secret for signature verification
6. Save

You'll receive a webhook URL to configure in the external service.

Step 3: Configure the External Service

Give the webhook URL to the external service or add it to your monitoring tool. The external service should POST JSON to the URL whenever the status changes.

Payload Format

The simplest payload Alert24 accepts:

{
  "status": "degraded",
  "message": "Email delivery delays in US-East region"
}

Alert24 extracts the status value and maps it to a service status. The message field is used for status page updates.

Nested Payloads

If the external service sends a more complex payload, configure the Status Field with dot notation to tell Alert24 where to find the status:

Status Field: data.attributes.current_status

{
  "data": {
    "attributes": {
      "current_status": "major",
      "description": "Database connectivity issues"
    }
  }
}

Dynamic Service Matching

Instead of linking a receiver to a fixed service, you can configure a Service Name Field to match the service by name from the payload. This lets a single receiver update multiple services:

{
  "service_name": "API Gateway",
  "status": "down",
  "message": "API Gateway is unreachable"
}

Status Mapping

Alert24 maps incoming status strings to service statuses. The default mapping covers common conventions:

Matching is case-insensitive. You can customize the mapping to match any naming convention your external service uses.

Security

HMAC Signature Verification

For production use, set an HMAC secret on your receiver. The sending service must include a signature header computed as HMAC-SHA256(request_body, secret).

Alert24 verifies the signature before processing the payload. If verification fails, the request is rejected with a 401 status and logged as an authentication failure.

The signature header name is configurable (default: X-Webhook-Signature).

Token-Based Authentication

Every webhook receiver has a unique 64-character token embedded in its URL. Even without HMAC verification, this token provides a baseline level of security — the URL is unguessable and specific to your receiver.

Automatic Incident Management

Webhook receivers can automatically create and resolve incidents:

• Auto-create incidents — When the service goes down or degraded, an incident is created with your chosen severity level
• Auto-resolve incidents — When the service returns to operational, open incidents created by this receiver are automatically resolved

What Happens on Status Change

When a webhook receiver updates a service's status, the full Alert24 pipeline runs:

1. Service status updates on your dashboard
2. SLA tracking records the status change for uptime calculations
3. Status page updates — A post is added to your public status page
4. Alert rules evaluate — Application-level alerts fire if configured
5. Team notifications — Your on-call team is notified through configured channels
6. Incidents — Auto-created/resolved if enabled

Delivery Logs

Every incoming webhook is logged with the source IP, payload, processing result, and any errors. View the last 50 deliveries for each receiver to debug integration issues.

Log entries show:

• Whether the webhook was processed, ignored (no status change), failed (bad payload), or auth_failed (bad signature)
• The raw status value extracted from the payload
• The mapped Alert24 status
• The previous and new service status

Use Cases

Monitoring services without status pages

Services like Pushmail, Simli, or internal tools don't have public status pages. Set up a webhook receiver and push status changes from your own monitoring checks (HTTP checks, synthetic tests, etc.).

Connecting Alert24 status pages

If a service you depend on publishes their status page on Alert24, they can configure an outbound webhook to push updates directly to your webhook receiver — giving you real-time, push-based status updates instead of polling.

CI/CD pipeline integration

Push deployment status from your CI/CD pipeline. Mark a service as "maintenance" when a deploy starts and "operational" when it completes.

# Mark service as maintenance before deploy
curl -X POST https://alert24.net/api/webhooks/incoming/<token> \
  -H "Content-Type: application/json" \
  -d '{"status": "maintenance", "message": "Deploying v2.4.1"}'

# Mark operational after deploy
curl -X POST https://alert24.net/api/webhooks/incoming/<token> \
  -H "Content-Type: application/json" \
  -d '{"status": "operational", "message": "Deploy v2.4.1 complete"}'

Custom health check integration

If you run your own health check infrastructure, push results to Alert24 instead of building a separate status dashboard.