Webhooks

Receive real-time HTTP notifications when zone or account events occur.

Overview

Webhooks let you subscribe to events from your hiddenprimary.ch account. When an event fires, we send an HTTP POST to your configured URL with a JSON payload signed with HMAC-SHA256.

Event Categories

CategoryEvents
zones transfer_ok, transfer_error, zone_created, zone_deleted, dnssec_enabled, dnssec_disabled, cert_*, domain_*
validation validation_failed, validation_warning, validation_ok
account login, api_key_created, api_key_deleted, subscription_changed
all All of the above

1. Create a Webhook

Go to Account → Webhooks in the portal, or use the API:

terminal
$ curl -X POST https://hiddenprimary.ch/v1/account/webhooks \
  -H "Authorization: Bearer $HP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","event_categories":["zones"]}'

The response includes a secret field — save it immediately. It is shown only once and cannot be recovered.

2. Payload Format

Every webhook POST has this JSON structure:

payload.json
{
  "event": "transfer_ok",
  "timestamp": "2026-03-19T12:00:00Z",
  "data": {
    "zone_id": 1,
    "zone_name": "example.ch",
    "serial": 2026031901
  }
}

3. Verify the Signature

Every request includes an X-Webhook-Signature header with format sha256=<hex>. Verify it by computing HMAC-SHA256 of the raw request body using your webhook secret:

Python
import hmac, hashlib
def verify(body, secret, signature):
  expected = "sha256=" + hmac.new(
    secret.encode(), body, hashlib.sha256
  ).hexdigest()
  return hmac.compare_digest(expected, signature)

4. Manage Webhooks

You can have up to 5 webhooks per account. Manage them via:

  • Portal: Account → Webhooks
  • API: GET/POST/DELETE /v1/account/webhooks

If you lose the secret, delete the webhook and create a new one. Toggle webhooks active/inactive without deleting them in the portal.

Zone Validation Events

When a zone is uploaded or transferred, hiddenprimary.ch automatically validates the zone content. Webhook events fire when the validation status changes:

EventDescription
validation_failedZone has errors (e.g. CNAME at apex, missing SOA)
validation_warningZone has warnings or infos but no errors (e.g. missing SPF)
validation_okZone passes all checks (previously had issues, now resolved)

Events only fire when the status changes — repeated transfers with the same content do not trigger duplicate webhooks.

Delivery

  • Timeout: 10 seconds per delivery attempt
  • Up to 3 delivery attempts with short backoff (0.5s, then 1s). Retried on network errors and on 5xx/429 responses; other 4xx responses are treated as permanent and not retried
  • Because of retries, your endpoint may receive the same event more than once — make processing idempotent (e.g. deduplicate on event content, or apply changes idempotently)
  • Your endpoint must use HTTPS
  • Return any 2xx status quickly to acknowledge receipt — anything else counts as a failed delivery

Next Steps