Skip to main content

API reference · /api/v1

Webhooks

Webhooks tell your system about changes as they happen. Add an endpoint in the reseller portal under API access → Webhooks, choose the events it receives, and Domain.af sends each event as a signed JSON POST to your server.

Events

EventSent when
domain.registeredA domain was registered
domain.renewedA domain was renewed
domain.transfer_completedA transfer to Domain.af completed
domain.transferred_awayA domain was transferred to another registrar
domain.expiringA domain is about to expire (sent at each reminder)
domain.expiredA domain expired
domain.nameservers_updatedA domain's nameservers changed
domain.lock_changedA domain's registrar lock was turned on or off
invoice.paidAn invoice was paid in full
webhook.testYou click “Send test event” in the portal

Request

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: DomainAf-Webhooks/1.0
X-DomainAf-Event: domain.renewed
X-DomainAf-Delivery: 5d0c8f3e-2b6a-4f1e-9a7c-1f2e3d4c5b6a
X-DomainAf-Timestamp: 1792656000
X-DomainAf-Signature: 3f9a…

{
  "id": "5d0c8f3e-2b6a-4f1e-9a7c-1f2e3d4c5b6a",
  "type": "domain.renewed",
  "created_at": "2026-10-22T08:00:00+00:00",
  "data": {
    "domain": {
      "id": 1042,
      "name": "example.af",
      "tld": ".af",
      "local_status": "active",
      "expires_at": "2028-10-22T00:00:00+00:00",
      "registered_at": "2025-10-22T00:00:00+00:00",
      "auto_renew": true,
      "registrar_lock": true,
      "reseller_client_id": null,
      "years": 2
    }
  }
}

Domain events carry data.domain. domain.renewed adds years, domain.expiring adds days (days left) and domain.nameservers_updated adds nameservers. invoice.paid carries data.invoice with id, number, status, currency, amount, amount_paid and paid_at. Webhooks never contain contact details or transfer codes: use the API to fetch more.

Verifying the signature

signed_payload = TIMESTAMP + "." + RAW_BODY
signature      = hex(hmac_sha256(signed_payload, ENDPOINT_SIGNING_SECRET))

Each endpoint has its own signing secret (starting whsec_), shown once when you add the endpoint or rotate the secret. It is not your API secret. Compute the signature over the exact bytes you received, compare in constant time, and reject timestamps more than 5 minutes old.

// PHP
$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_DOMAINAF_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_DOMAINAF_SIGNATURE'] ?? '';
$ok   = abs(time() - (int) $ts) <= 300
     && hash_equals(hash_hmac('sha256', $ts.'.'.$body, $secret), $sig);

// Node.js
const expected = crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
const ok = Math.abs(Date.now() / 1000 - Number(ts)) <= 300
  && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));

Responding and retries

  • Answer with any 2xx status within 10 seconds. Redirects are not followed and count as failures.
  • Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then abandoned. You can redeliver any event from the portal.
  • After 20 failed attempts in a row the endpoint is turned off and you get a portal notification. Turn it back on once your receiver is fixed.
  • Events can arrive more than once or out of order. Use id (also in X-DomainAf-Delivery) to ignore duplicates, and fetch the domain from the API if you need its latest state.

Endpoint requirements

  • A public https:// URL. Private, loopback and reserved addresses are refused
  • Up to 10 endpoints per reseller account
  • Delivery history is kept for 30 days