ReachScore Docs
API Reference

Webhooks

Receive real-time notifications via HTTP POST when events occur. Configure endpoints to be notified when tests complete, alerts trigger, or domain health changes.

Available Events

test.completedTest finished running
test.failedTest failed to complete
alert.triggeredAlert rule triggered
domain.verifiedDomain verification succeeded
domain.health_changedDomain health status changed

Create a new webhook endpoint. Returns the endpoint with a signing secret for verifying webhook signatures.

Request Bodyrequired

urlstring<uri>required

HTTPS URL to receive webhook events

eventsarrayrequired

Event types to subscribe to

test.completedtest.failedalert.triggereddomain.verifieddomain.health_changed
enabledboolean

Whether the endpoint is active (default: true)

Response

idstring

Unique webhook endpoint ID (whe_xxx)

objectstring

Always 'webhook_endpoint'

urlstring<uri>
eventsarray
enabledboolean
secretstring

Signing secret for verifying payloads

created_atstring<date-time>

Example Request

curl -X POST https://api.reachscore.co/v1/webhooks/endpoints \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/reachscore",
    "events": ["test.completed", "alert.triggered"]
  }'

Example Response

{
  "id": "whe_5aK0nO4pRtU6",
  "object": "webhook_endpoint",
  "url": "https://yourapp.com/webhooks/reachscore",
  "events": ["test.completed", "alert.triggered"],
  "enabled": true,
  "secret": "whsec_abc123xyz...",
  "created_at": "2026-03-11T10:30:00Z"
}

Verifying Signatures

All webhook payloads include a signature header for verification. This ensures the payload was sent by ReachScore and hasn't been tampered with.

Headers Included

X-Reachscore-Signature: HMAC-SHA256 signature
X-Reachscore-Timestamp: Unix timestamp of the request
X-Reachscore-Event-ID: Unique event identifier
Node.js Example
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
Previous: MonitorsNext: Alerts