How to Setup Webhook Notifications

Webhooks allow you to receive real-time notifications by sending HTTP POST requests to a URL endpoint that you specify. This is useful for integrating ZoneWatcher with your own systems, applications, or custom notification workflows.

When an event occurs (such as a DNS change), ZoneWatcher will send a JSON payload to your webhook endpoint containing detailed information about the event.

ZoneWatcher sends webhook notifications as JSON POST requests. Here's an example payload for a zone change event:

{
  "event": "zone.changed",
  "zone": {
    "id": "zne_abc123",
    "domain": "example.com"
  },
  "check": {
    "id": "chk_xyz789",
    "changed_records": 3,
    "created_at": "2024-01-15T10:30:00.000Z",
    "url": "https://zonewatcher.com/checks/chk_xyz789"
  },
  "notification": {
    "title": "example.com has been modified",
    "message": "We have detected a DNS change in example.com on 2024-01-15. Total Records Changed: 3"
  }
}

The payload structure will vary depending on the event type, but all webhooks include the event field and relevant context about what triggered the notification.

To ensure that webhook requests are genuinely from ZoneWatcher, you can configure a signing secret. When configured, ZoneWatcher will sign each webhook request using HMAC-SHA256, and include the signature in the request headers.

You can verify the signature on your server to confirm the request's authenticity. The signing secret is optional but highly recommended for production environments.

Your webhook endpoint should:

• Accept HTTP POST requests
• Accept JSON payloads with Content-Type: application/json
• Respond with a 2xx status code (e.g., 200 OK) to acknowledge receipt
• Process requests quickly (within 30 seconds) to avoid timeouts
• Be publicly accessible over HTTPS (recommended for security)

Example endpoint URL: https://your-app.com/webhooks/zonewatcher

ZoneWatcher allows you to create unlimited Notification Channels, which can be customized to send notifications to different webhook endpoints.

Once you have your webhook endpoint ready, you can create a new Notification Channel by:

• Selecting "Webhook" as the channel type
• Giving it a descriptive name (e.g., "Production Webhook")
• Entering your webhook endpoint URL
• Optionally adding a signing secret for security
• Selecting which events you want to receive notifications for

Available notification events include:

• Zone Changed
• New Zone Discovered
• Zone Expiring Soon
• Zone Expired
• Zone Renewed
• Zone Nameservers Changed
• Zone Certificate Issued
• Provider Auto-Disabled

After creating your webhook notification channel, we recommend testing it to ensure your endpoint is correctly configured and can receive notifications from ZoneWatcher.

You can monitor your server logs to verify that webhook requests are being received successfully and that your application is processing them as expected.

• Always validate the webhook signature if you've configured a signing secret
• Use HTTPS for your webhook endpoint to ensure data is encrypted in transit
• Implement proper error handling and logging in your webhook handler
• Process webhook events asynchronously if they require time-consuming operations
• Return a successful response quickly to avoid timeouts
• Store the raw webhook payload for debugging purposes