Webhooks

Overview

Webhooks allow your application to receive HTTP POST notifications when events occur in a Whatalo store. Instead of polling the API, your server receives data automatically.

How Webhooks Work

1. An event occurs (e.g., new order placed)
2. Whatalo sends a POST request to your registered URL
3. Your server processes the payload and returns 2xx
4. If delivery fails, Whatalo retries with exponential backoff

Managing Webhook Endpoints

List Webhooks

GET /v1/webhooks

Required scope: read:webhooks

Create Webhook

POST /v1/webhooks

{
  "url": "https://your-server.com/webhooks/whatalo",
  "events": ["order.created", "order.updated"]
}

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint URL (must be HTTPS)
`events`	string[]	Yes	Event types to subscribe to
`secret`	string	No	Custom signing secret (auto-generated if omitted)

Webhook URLs must use HTTPS. HTTP endpoints are rejected.

Required scope: write:webhooks

Update Webhook

PATCH /v1/webhooks/:id

Required scope: write:webhooks

Delete Webhook

DELETE /v1/webhooks/:id

Required scope: write:webhooks

Event Types

Event	Trigger
`order.created`	New order placed
`order.updated`	Order status or data changed
`product.created`	New product created
`product.updated`	Product data changed
`product.deleted`	Product deleted
`customer.created`	New customer registered
`customer.updated`	Customer data changed

Webhook Payload

All webhook payloads follow this structure:

{
  "event": "order.created",
  "timestamp": "2026-03-01T15:00:00Z",
  "data": {
    "id": "ord_abc123",
    "order_number": 1042,
    "status": "pending",
    "total": 8997
  }
}

Webhook Security

Every webhook delivery includes an X-Whatalo-Signature header containing an HMAC-SHA256 signature. Verify this to ensure the payload was sent by Whatalo.

Verification Example

Node.js

import crypto from "crypto";

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Policy

If your endpoint returns a non-2xx status code, Whatalo retries with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the webhook delivery is marked as failed. You can retry manually from the Developer Dashboard.

On this page