Guides Webhooks

Webhook Integration Guide

Receive DNS change events in your own systems with signed payloads.

7 min read
By Tom Beech Published March 2026

How webhooks work

When DriftWatch detects a DNS change that matches one of your alert rules, it sends a JSON POST to your webhook endpoint. Every request is signed with HMAC-SHA256 so you can verify it came from DriftWatch.

Payload format

{
  "event": "dns.change.detected",
  "timestamp": "2026-03-11T14:32:00Z",
  "domain": {
    "id": 42,
    "name": "example.com"
  },
  "record": {
    "type": "A",
    "name": "example.com",
    "previous_value": "93.184.216.34",
    "new_value": "198.51.100.1",
    "previous_ttl": 3600,
    "new_ttl": 300
  },
  "change_type": "modified",
  "change_id": 1847
}

Verifying signatures

DriftWatch includes the HMAC-SHA256 signature in the X-DriftWatch-Signature header. The signing secret is shown when you create the webhook channel.

# PHP example
$signature = hash_hmac('sha256', $requestBody, $signingSecret);
$valid = hash_equals($signature, $request->header('X-DriftWatch-Signature'));

# Node.js example
const crypto = require('crypto');
const signature = crypto.createHmac('sha256', signingSecret)
  .update(requestBody).digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(signature), Buffer.from(headerSignature)
);

Retry policy

If your endpoint returns a non-2xx status code, DriftWatch retries with exponential backoff:

  • 1st retry: 30 seconds
  • 2nd retry: 2 minutes
  • 3rd retry: 10 minutes

After 3 failed attempts, the delivery is marked as failed in your alert logs.

Common integrations

  • Jira / Linear - Create tickets automatically when critical DNS changes are detected
  • Terraform - Trigger a state comparison when unexpected drift is found
  • Custom dashboards - Feed change data into Grafana, Datadog, or your internal monitoring
  • Compliance logging - Archive all DNS changes to your audit trail

Related guides