Webhooks Overview

Webhooks provide real-time event notifications by sending HTTP POST requests directly to your configured endpoint. This allows your application to receive immediate updates about domain and order events without the need for polling.

Important: Read this entire document before you begin. Webhook setup must be completed in a specific order (see Required setup order below).

Configuration

Webhooks can be configured in the Reseller Control Panel under Account Settings > Event notifications.

Webhook Components

1. Webhook URL: Enter the HTTPS endpoint URL where you want to receive event notifications. This must be a publicly accessible URL that can accept POST requests.

2. Shared Secret: When you configure or update your webhook URL, a new shared secret is automatically generated. This secret is used to sign the webhook payloads for security verification.

   • The shared secret is reset every time you change the webhook URL
   • Store this secret securely - you'll need it to verify incoming webhook requests
   • Never expose your shared secret in client-side code or public repositories

3. Enable Events: Select which events you want to receive via webhooks. Available events include:

   • Domain events (created, registered, renewed, expired, deleted)
   • Order status changes
   • Transfer status updates
   • Verification status changes
   • And more (see Event Notifications Overview for complete list)

Required setup order

Important: As of 2026-07-17, complete these steps in the exact order shown. Doing them out of order — for example, enabling the webhook before selecting events or saving the URL — can leave webhooks non-functional.

In the Reseller Control Panel, under Account Settings > Event notifications:

1. Select your events — In the WEBHOOK column, check each event you want delivered by webhook.
2. Set the Webhook URL — Click Edit, enter your HTTPS endpoint URL, and click Save. Saving a URL resets your Shared Secret, so do this before the next step.
3. Store the Shared Secret — Click Reveal, then copy the secret and store it securely (in a secrets manager such as 1Password, for example). You need this value to verify incoming webhook requests.
4. Configure your receiving system — Update your endpoint to accept and verify incoming webhooks signed with the new Shared Secret from step 3 (see the Verifying a webhook (receiver side) section below).
5. Enable webhooks — Turn on the WEBHOOK toggle in Global Settings. Do this last, once the previous steps are complete.

Webhook Payload

When an event occurs, a signed JSON payload is sent to your configured webhook URL via HTTP POST.

Payload Structure

{
   "created_date" : "2026-07-15T23:50:44Z",
   "id" : "42a07a90-323e-4920-a26e-b3624b419832",
   "notification_type" : "opensrs.domain.created",
   "payload" : {
      "@type" : "type.googleapis.com/google.protobuf.Struct",
      "value" : {
        // Event-specific data
        // See individual event documentation for details
      }
   }
}

Signature scheme

Each outgoing webhook is sent as an HTTP POST with the following signing-related headers:

What is signed: the raw HTTP request body, byte-for-byte. The HMAC is computed before the body is transmitted and is not affected by re-serialization at the receiver — so receivers MUST hash the bytes they received, before any JSON parse/re-marshal.

The signing secret: signing_secret is your shared secret used exactly as issued — the full 36-character string (32 hexadecimal digits and 4 hyphens, e.g. 42a07a90-323e-4920-a26e-b3624b419832). Those 36 characters are used verbatim as the HMAC key; do not strip the hyphens or decode the UUID text into its 16 raw bytes.

Verifying a webhook (receiver side)

1. Read the raw request body as bytes (do not parse and re-serialize first).
2. Compute HMAC-SHA256(body, your_stored_secret) and hex-encode.
3. Compare against the HMAC-Signature header using a constant-time comparison (e.g. hmac.Equal in Go, hmac.compare_digest in Python).
4. If they match, the request is authentic.

Webhook Response

Your endpoint should:

• Return a 2xx HTTP status code to acknowledge successful receipt
• Process the webhook asynchronously if handling it takes time — return 2xx first, then do the work
• Respond quickly (within 5 seconds) to avoid timeouts

Warning: Your endpoint must return a 2xx status code on successful receipt. Any other response is treated as a failed delivery — depending on the status code it is either dropped or retried (see the status table under Retry Policy below). If your receiver does not return 2xx, delivery is not recognized as successful and webhooks may not work as expected.

Retry Policy

The HTTP status code your endpoint returns determines whether a delivery is treated as successful and whether it is retried:

When a delivery is retried — a 5xx response, or the endpoint being unreachable or timing out:

• Retries use exponential backoff
• Maximum of 5 retry attempts over 24 hours
• After the maximum attempts, the event is marked as failed

Security Best Practices

1. Always use HTTPS for your webhook endpoint
2. Verify signatures on all incoming requests
3. Store your shared secret securely (environment variables, secrets management system)
4. Implement idempotency - handle duplicate events gracefully
5. Rate limit your endpoint to prevent abuse
6. Log webhook events for debugging and audit purposes

Webhook vs Polling

Advantages of webhooks over polling:

• Real-time updates: Receive events immediately when they occur
• Efficiency: No need for repeated API calls to check for new events
• Scalability: Reduces API load and improves system performance
• Simplicity: Cleaner architecture with event-driven design

For information about available events and their parameters, see the Event Notifications Overview.