Webhooks

Webhooks allow you to receive real-time notifications when events occur in the system.

Currently, we support the following webhook topics:

reviews.created - Triggered when a new review is created

Create a new webhook subscription to receive notifications for specific events.

POST `/api/1.0/webhook`

Query Parameters

`id` int (required)

The unique webshop ID.

`code` string (required)

Your personal API code.

Body Parameters (JSON)

`url` string (required)

The URL where webhook events will be sent

`topic` string (required)

The webhook topic to subscribe to. Currently only "reviews.created" is supported

`is_active` boolean

Whether the webhook subscription is active. Default true. If false, no events will be sent to the webhook URL

Example:

{
    "url": "https://your-domain.com/webhook",
    "topic": "reviews.created"
}

Response

Success (200 OK)

{
    "status": "success",
    "message": "Webhook subscription created",
    "data": {
        "webhook_id": 123,
        "url": "https://your-domain.com/webhook",
        "topic": "reviews.created",
        "secret": "your_webhook_secret"
    }
}

Error Responses

Bad Request (400)

{
    "status": "error",
    "message": "Invalid webhook URL or topic"
}

Unauthorized (401)

{
    "status": "error",
    "message": "Unauthorized"
}

Webhook Delivery

When an event occurs, we will send a POST request to your webhook URL with the following:

Headers

Content-Type: application/json
X-Hash: SHA-256 HMAC signature of the payload

Payload

The payload will be sent as JSON in the request body. For the reviews.created topic, the payload will contain a single review object with the same structure as the reviews returned by the ratings retrieve endpoint.

Verifying Webhook Signatures

To verify that the webhook request came from us, you should verify the X-Hash header. Here's how to do it:

<?php

// Get the webhook secret from your webhook subscription
$secret = 'your_webhook_secret';

// Get the raw request body
$payload = file_get_contents('php://input');

// Get the X-Hash header
$signature = $_SERVER['HTTP_X_HASH'] ?? '';

// Calculate the expected signature
$expectedSignature = hash_hmac('sha512', $payload, $secret);

// Compare signatures
if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Process the webhook payload
$data = json_decode($payload, true);

Notes

Webhook requests will be retried if they fail (non-2xx response)
Always verify the webhook signature to ensure the request came from us