Webhooks notify your application about selected Domain Nexus events. Configure a public HTTPS receiver, verify the signature over the original body and make processing safe when a delivery is retried.
IN THIS ARTICLE
01 Create the endpoint
Use the reseller portal's Webhooks page or the permitted POST /v2/webhooks route. Provide the receiver URL, a recognisable label and the event patterns you actually need. Save the signing secret when it is revealed; it is separate from your outbound API credential.
The receiver must be reachable over public HTTPS with a valid certificate. The delivery client does not follow redirects. Point it directly at the final handler and avoid a login page or intermediate URL.
02 Verify the incoming request
Read X-Webhook-Timestamp, X-Webhook-Delivery and X-Webhook-Signature. Compute the expected signature from the timestamp, delivery identifier and exact raw request body:
$signed = $timestamp . '.' . $deliveryId . '.' . $rawBody;
$expected = base64_encode(hash_hmac('sha256', $signed, $webhookSecret, true));
$valid = hash_equals($expected, $receivedSignature);
Use a constant-time comparison, enforce a suitable timestamp window and store processed delivery identifiers. Do not decode and re-encode the JSON before checking the signature. The documented signing helper uses a five-minute default freshness window.
03 Process events reliably
- Verify the request before trusting its contents.
- Read the event envelope's
id,type,version,created_atanddata. - Persist the event or enqueue it in your own system before returning a successful response.
- Process it idempotently, using the event and delivery references to prevent duplicate business actions.
- Read the current owned resource through the API when you need its latest state, especially if related events arrive close together.
Can I replay a webhook without repeating the domain operation?
List an endpoint's deliveries through GET /v2/webhooks/{endpointId}/deliveries. A permitted replay uses POST /v2/webhooks/deliveries/{deliveryId}/replay with an idempotency key. Fix the receiver first, then replay the owned delivery.
The sender retries selected transient failures with backoff. Do not make a slow receiver perform an entire paid domain operation before acknowledging the webhook. Persisting the event promptly and processing it separately reduces timeout-driven duplicates.
For a duplicate already accepted event, your receiver can acknowledge it without applying the business change again. Keep secrets out of access logs and return a simple response that contains no confidential customer data.