The webhook system is built upon the existing email notification process and allows automatic delivery of domain mutation events to external systems.

1. Enabling or Disabling Webhooks

The IPs to whitelist are: 185.87.187.130 and 34.34.72.46.

Webhook notifications can be managed via the modifyResellerRequest API call. This API allows enabling/disabling webhook notifications and configuring webhook parameters.

✅ API Parameters

<?xml version="1.0" encoding="UTF-8"?>
<openXML>
    <credentials>
        <username>username</username>
        <password>password</password>
        <hash></hash>
    </credentials>
    <modifyResellerRequest>
        <notificationsSettings>
            <isWebhookEnabled>1</isWebhookEnabled>    <!-- 0/1/true/false -->
            <webhookSettings>
                <host>https://webhook.example.com/endpoint</host>
                <apiKey>your_api_key_here</apiKey>
                <signatureSecret>your_signature_secret</signatureSecret>    <!-- optional -->
            </webhookSettings>
        </notificationsSettings>
    </modifyResellerRequest>
</openXML>

curl --location --request PUT '<op_api_host>/v1beta/resellers/<resellerId>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <op_auth_token>' \
--data-raw '{
  "notifications_settings": {
    "is_webhook_enabled": true,
    "webhook_settings": {
      "host": "https://webhook.example.com/endpoint",
      "api_key": "your_api_key_here",
      "signature_secret": "your_signature_secret"
    }
  }
}'

{
  "id": 123,
  "schemaVersion": "1.0",
  "eventType": "outgoingTransferCompleted",
  "timeStamp": 1757662480,
  "data": {
    "domainId": 456,
    "domain": "example.net",
    "action": "outgoing transfer succeeded",
    "status": "DEL",
    "orderDate": "2023-08-08",
    "activationDate": null,
    "renewalDate": null,
    "expirationDate": null,
    "comments": "Message from registry: Message1",
    "registryMessage": null
  }
}

Request Headers

Each webhook request includes the following headers:

📬 Example Webhook Request

curl -v --location --request POST <webhook_host_url> \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <webhook_apiKey>' \
--header 'User-Agent: Openprovider-Webhook/1.0' \
--header 'X-Webhook-Agent: Openprovider-Webhook/1.0' \
--header 'X-Webhook-Event: outgoingTransferCompleted' \
--header 'X-Webhook-Signature: t=1757662480,v1=<hex_hmac>' \
--data-raw '{
  "id": 1,
  "schemaVersion": "1.0",
  "eventType": "outgoingTransferCompleted",
  "timeStamp": 1757662480,
  "data": {
    "domainId": 1,
    "domain": "example.net",
    "action": "outgoing transfer succeeded",
    "status": "DEL",
    "orderDate": "2023-08-08",
    "activationDate": null,
    "renewalDate": null,
    "expirationDate": null,
    "comments": "Message from registry: Message1",
    "registryMessage": null
  }
}'

• HTTP 200 → Webhook considered successfully delivered.

• Any other code → Delivery failed, and the retry mechanism is triggered.

🔁 Retry Policy

If a webhook fails (non-200 response or timeout), the system retries delivery up to 5 times using a progressive delay schedule:

If all attempts fail, the system:

• Logs the event as undelivered.

• Sends an email notification to the reseller with subject: [OPENPROVIDER] Failed webhooks

3. HMAC Signature Validation (Optional)

To enable signature validation, set signatureSecret in webhookSettings (see Section 1). When configured, each request is signed using HMAC-SHA256, allowing your server to verify the request originated from Openprovider and that the payload was not modified in transit.

Signature Header

The header contains two values:

• t — Unix timestamp (seconds) at the time the webhook was sent.

• v1 — HMAC-SHA256 hex digest of the signed string.

Signature Formula

Where:

• timestamp is the t= value from the X-Webhook-Signature header.

• body is the raw JSON payload exactly as received.

• signatureSecret is the secret configured in your webhook settings.

Verifying on Your Server

1. Extract t and v1 from the X-Webhook-Signature header.

2. Reconstruct: stringToSign = t + "." + rawBody

3. Compute: HMAC-SHA256(stringToSign, signatureSecret)

4. Compare your result with the v1 value. If they match, the request is authentic.

Note: Use a constant-time comparison to prevent timing attacks.

Secret rotation is fully controlled by the reseller through webhook settings, with no downtime required.

4. Webhook Event Types