Webhooks

What Are Webhooks#

Webhooks let you receive real-time HTTP notifications when events occur in Opterius Commerce. When a subscribed event fires, Commerce sends an HTTP POST request to your configured URL with a JSON payload describing the event.

This is useful for keeping external systems — custom dashboards, accounting software, provisioning pipelines — in sync without polling the API.

Supported Events#

Configuring Webhook Endpoints#

1. Go to Admin → Settings → Webhooks.
2. Click Add Endpoint.
3. Enter your endpoint URL (must be publicly accessible via HTTPS).
4. Enter the shared secret you want to use for signature verification.
5. Select the events you want to subscribe to, or choose All Events.
6. Click Save.

[!TIP] Use webhook.site to get a free temporary URL for testing. You can inspect every incoming payload in real time before building your receiver.

Payload Format#

All webhook payloads follow the same structure:

{
  "event": "invoice.paid",
  "timestamp": "2026-04-15T14:22:30Z",
  "signature": "sha256=a1b2c3d4...",
  "data": {
    "id": 305,
    "invoice_number": "INV-0305",
    "status": "paid",
    "total": 2200,
    "currency_code": "USD",
    "paid_at": "2026-04-15T14:22:28Z"
  }
}

Verifying Signatures#

Commerce signs every webhook request using HMAC-SHA256 with the shared secret you configured. Always verify the signature before processing the payload to prevent spoofed requests.

The signature is in the signature field of the JSON body as sha256={hex_digest}.

PHP example:

$rawBody = file_get_contents('php://input');
$secret = 'your-shared-secret';

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $payload['signature'];

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

[!WARNING] Compute the HMAC over the raw request body, not a re-encoded version of the decoded JSON. Re-encoding can alter key order or whitespace, producing a different hash.

Retry Behaviour#

If your endpoint does not return a 2xx HTTP response, Commerce will retry the delivery:

After 3 failed retries, the delivery is marked as failed. You can view failed deliveries and manually replay them from Admin → Settings → Webhooks → Delivery Log.

Your Endpoint Requirements#

• Must be reachable over HTTPS (HTTP endpoints are rejected).
• Must return a 2xx status code within 10 seconds.
• Should return quickly — offload any heavy processing to a background queue on your side.

[!IMPORTANT] Webhook deliveries can occasionally arrive out of order or be delivered more than once during retries. Design your receiver to be idempotent — processing the same event twice should produce the same result.