Docs

REST API

Webhooks

Get a signed HTTP request whenever your profile changes, and how to verify it.

Instead of polling the API, add a webhook and we call your server when something changes. Webhooks come with the Pro plan and above (see Plans). Add one in the panel under Developers → Webhooks.

Events

Event When
profile.updated A profile field changed. data.changed lists which fields.
avatar.changed An avatar was uploaded or deleted.
verification.added A verified account was added (data.network, data.identifier).
verification.removed A verified account was removed.
ping The test you send from the panel.

The request

We POST JSON to your address. It must be a public https URL: private, loopback and link-local addresses are refused, redirects are not followed, and credentials in the URL are not allowed.

{
  "id": "5b1e0b0e-6a4c-4e5e-9c53-1d3f4b8c8d11",
  "type": "profile.updated",
  "created_at": "2026-11-18T12:00:00+00:00",
  "data": {
    "changed": ["headline"],
    "username": "javid",
    "profile_url": "https://avatarak.ir/javid",
    "email_hashes": ["9d86ec2b…"]
  }
}

email_hashes are the SHA-256 hashes of your own verified addresses, so you can match the event to a user on your side. The payload never contains an email address.

Headers: Avatarak-Event, Avatarak-Delivery (the event id, use it to ignore duplicates) and Avatarak-Signature.

Verify the signature

Each webhook has a secret (whsec_…) shown once when you create it. The signature header is t=<unix time>,v1=<hex>, where v1 is HMAC-SHA256(secret, "<t>.<raw body>"). Check it against the raw request body, and reject old timestamps (5 minutes is a good limit).

use Avatarak\Webhook;

$ok = Webhook::verify(file_get_contents('php://input'), $_SERVER['HTTP_AVATARAK_SIGNATURE'] ?? null, $secret);
import { verifyWebhook } from '@avatarak/client';

const ok = await verifyWebhook(rawBody, req.headers['avatarak-signature'], secret);

Retries

Answer with any 2xx within 8 seconds. Otherwise we retry up to 5 times, with growing pauses (30 s, 2 min, 10 min, 1 h). After 20 failures in a row the webhook is switched off automatically; turn it back on in the panel. Make your handler idempotent: the same event can arrive more than once.