Webhook Notification System

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 API Example

<?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>

🧾 REST API Example

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"
    }
  }
}'

🔍 Validation

When webhookSettings are saved, the system automatically validates the host URL by sending a test webhook. A successful webhook (HTTP 200 OK) confirms the configuration.

If signatureSecret is configured, the test webhook includes the same X-Webhook-Signature header as production webhooks, allowing you to validate your signature verification logic end-to-end during setup.

2. Webhook Processing

When domain-related events occur, the system sends a POST request to the configured webhook endpoint.

Payload Structure

The payload includes schemaVersion at the root level. domainId is located inside the data object.

{
  "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
  }
}'