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
| Event | Sent when |
|---|---|
domain.registered | A domain was registered |
domain.renewed | A domain was renewed |
domain.transfer_completed | A transfer to Domain.af completed |
domain.transferred_away | A domain was transferred to another registrar |
domain.expiring | A domain is about to expire (sent at each reminder) |
domain.expired | A domain expired |
domain.nameservers_updated | A domain's nameservers changed |
domain.lock_changed | A domain's registrar lock was turned on or off |
invoice.paid | An invoice was paid in full |
webhook.test | You 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
2xxstatus 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 inX-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