How to use webhooks?

What is a webhook?

A webhook is a way for one application to automatically send information to another application when a specific event occurs.

Instead of repeatedly checking for updates, a webhook allows systems to communicate in real time. When an event occurs, such as an order being created, a payment being completed, or a service being provisioned, the system sends an HTTP request with event data to a URL you specify.

This approach enables you to automate workflows, synchronize data between systems, and respond to events in real time without manual intervention.

How webhooks work

1. You create a webhook and provide a destination URL (also called an endpoint).
2. An event occurs in the system.
3. The system sends an HTTP POST request to your endpoint.
4. Your application receives the event data and performs any required actions.

Example

For example, you can configure a webhook to notify your application whenever a new IP address is provisioned. When the event occurs, our platform sends the event details to your webhook URL, allowing your application to automatically update records, trigger workflows, or notify team members.

Benefits of webhooks

• Receive event notifications in real time.
• Automate repetitive tasks and workflows.
• Reduce the need for constant API polling.
• Integrate our platform with your internal tools and third-party services.
• Keep systems synchronized automatically.

How do I configure one?

You can create, manage, and monitor webhooks from the Webhooks page within your company profile.

Accessing the webhooks page

1. Open your Company Profile.
2. Navigate to Webhooks.
3. The Webhooks page displays all configured webhooks and their status.

Creating a webhook

To create a new webhook:

1. Open the Webhooks page.
2. Click Create Webhook.
3. Enter a Name for the webhook.
4. Enter the Endpoint URL where webhook events should be delivered.
5. Select one or more Events that should trigger webhook notifications.
6. Click Create.

After the webhook has been created, the system will generate and display a Webhook Secret. This secret is used to verify that incoming webhook requests originate from Priority Prospect.

Keep your webhook secret secure and do not share it publicly.

Managing existing webhooks

From the Webhooks page, you can:

• View all configured webhooks.
• Edit webhook settings, including the name, endpoint URL, and subscribed events.
• Enable or disable webhooks as needed.
• Delete webhooks that are no longer required.

Viewing webhook logs

Each webhook includes a log history that allows you to review delivery attempts and troubleshoot issues.

Webhook logs contain information such as:

• Event type
• Delivery date and time
• HTTP response status code
• Delivery status
• Error details, when applicable

Reviewing webhook logs can help identify configuration issues, endpoint errors, or failed deliveries.

What events exist?

Webhooks can be triggered by a variety of events that occur within the platform. When a subscribed event occurs, a notification is automatically sent to your configured webhook endpoint.

Domain events

Email events

IP address events

Hosting events

Invoice events

Order events

Software events

New webhook events may be added over time as new features and services become available. The most up-to-date list of events can always be found when creating or editing a webhook.

What payloads are sent?

Each webhook event includes a JSON payload containing information about the event that occurred.

The exact structure of the payload depends on the event type. For example, a domain-related event will contain different information than an invoice or software-related event.

Because payload structures may evolve as new features and fields are added, we maintain the authoritative payload specifications in our API documentation.

Visit our API documentation: https://api.priorityprospect.com/docs/

How do I verify signatures?

Every webhook request is signed using your webhook secret. Verifying the signature ensures that:

• The request was sent by our platform.

• The request payload was not modified in transit.

Webhook headers

Every webhook request includes the following headers:

X-Webhook-Timestamp: <timestamp>
X-Webhook-Signature: sha256=<signature>
X-Webhook-Delivery-Id: <delivery-id>
X-Webhook-Event: <event-key>
X-Webhook-Id: <webhook-id>

How signature verification works

The webhook signature is generated using HMAC-SHA256 over the following string:

<timestamp>.<raw request body>

Use your webhook secret as the HMAC key.

Verification steps

1. Read the X-Webhook-Timestamp header.

2. Read the X-Webhook-Signature header.

3. Read the raw request body exactly as received.

4. Generate an HMAC-SHA256 signature using:

   <timestamp>.<raw request body>
   

5. Prefix the generated hash with sha256=.

6. Compare the generated signature with the value from X-Webhook-Signature using a constant-time comparison function.

7. Reject the request if the signatures do not match.

Important: Verify the signature using the raw request body before parsing JSON. Parsing and re-serializing JSON can change whitespace, formatting, or key order and cause signature verification to fail.

PHP

$secret = 'your_webhook_secret';

$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $body,
    $secret
);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Python

import hashlib
import hmac

secret = "your_webhook_secret"

timestamp = request.headers["X-Webhook-Timestamp"]
signature = request.headers["X-Webhook-Signature"]
body = request.get_data()  # Raw request body (Flask example)

expected = "sha256=" + hmac.new(
    secret.encode(),
    timestamp.encode() + b"." + body,
    hashlib.sha256,
).hexdigest()

if not hmac.compare_digest(expected, signature):
    return "", 401

JavaScript (Node.js)

import crypto from "crypto";

const secret = "your_webhook_secret";

const timestamp = req.headers["x-webhook-timestamp"];
const signature = req.headers["x-webhook-signature"];
const body = req.rawBody; // Raw Buffer

const expected =
  "sha256=" +
  crypto
    .createHmac("sha256", secret)
    .update(Buffer.concat([
      Buffer.from(timestamp),
      Buffer.from("."),
      body,
    ]))
    .digest("hex");

if (
  !crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
) {
  return res.sendStatus(401);
}

Prevent replay attacks

In addition to verifying the signature, we recommend validating the timestamp to prevent replay attacks.

For example, reject requests whose timestamp differs from the current time by more than 5 minutes.

current_time - webhook_timestamp > 300 seconds

Choose a time window that matches your application's security requirements.

Common causes of failed verification

• Using a parsed or re-serialized JSON payload instead of the raw request body.

• Using the wrong webhook secret.

• Omitting the timestamp when generating the signature.

• Modifying the request body before verification.

• Comparing signatures with a non-constant-time comparison function.

• Allowing middleware, proxies, or frameworks to alter the request body before verification.

Troubleshooting

If signature verification consistently fails:

1. Verify that the webhook secret matches the endpoint that received the webhook.

2. Log the received timestamp and signature headers.

3. Confirm that the raw request body is being used.

4. Verify that the generated signature includes:

   <timestamp>.<raw request body>
   

5. Check whether any middleware modifies the request body before your application receives it.

6. Confirm that the generated signature includes the sha256= prefix.