Skip to content

Knowledgebase

Receive and verify Domain Nexus webhook deliveries

domain-nexus, development

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.

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:

Code or configuration example
$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

  1. Verify the request before trusting its contents.
  2. Read the event envelope's id, type, version, created_at and data.
  3. Persist the event or enqueue it in your own system before returning a successful response.
  4. Process it idempotently, using the event and delivery references to prevent duplicate business actions.
  5. 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.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support