Webhooks
Pushizo delivers events from your app (deliveries, opens, subscriptions, users, events, conversions, campaigns) to your server over HTTPS, signed. Endpoints are managed in the dashboard under Developer → Webhooks or…
Pushizo delivers events from your app (deliveries, opens, subscriptions, users, events, conversions, campaigns) to your server over HTTPS, signed. Endpoints are managed in the dashboard under Developer → Webhooks or via the Public API (/v1/apps/{app_id}/webhooks, admin scope).
To transform the body with a Liquid template, narrow events with conditions (e.g. only a specific campaign) and preview the result, see Event Streams. delivery.* events also carry the data.campaign_id field (null for non-campaign messages).
Event types
| Group | Events |
|---|---|
| Message | message.queued, message.completed, message.failed |
| Delivery | delivery.sent, delivery.delivered, delivery.failed, delivery.opened, delivery.clicked, delivery.bounced, delivery.complained, delivery.unsubscribed |
| In-app | in_app.impression, in_app.clicked (button_id), in_app.dismissed |
| Subscription | subscription.created, subscription.unsubscribed, subscription.invalidated |
| User | user.created, user.updated, user.merged, user.deleted |
| Event | event.received (an event name filter is required: event_filters.event_names, at least one name) |
| Conversion | conversion.created |
| Campaign | campaign.scheduled, campaign.started, campaign.completed |
| Journey | journey.entered, journey.step_completed, journey.completed, journey.exited |
Email/SMS feedback (Phase 10, see messaging.md) is delivered with the same events: provider delivery as delivery.delivered; open pixel/click redirect and provider open/click events as delivery.opened / delivery.clicked (with the url field); a hard bounce as delivery.failed (error_code: "bounced", for backward compatibility) and delivery.bounced (bounce_type: "hard", error_code, error_message) + subscription.invalidated; a complaint as delivery.complained, an unsubscribe link as delivery.unsubscribed (each once per delivery) + subscription.unsubscribed; SMS STOP as subscription.unsubscribed.
In-app events are produced from the SDK's impression/click/dismiss reports: data = { in_app_message_id, name, subscription_id, user: { id, external_id }, button_id? }. delivery.* and in_app.* events can be grouped in batch mode.
Journey events (Phase 11, see journeys.md) carry these common data fields: { journey_id, run_id, version, user: { id, external_id } }. Additional fields by event:
journey.entered:entry(entry context).journey.step_completed:node_id,node_type,status(completed/skipped/failed),branch,result. Can be grouped in batch mode.journey.completedandjourney.exited:reason(e.g.manual,journey_archived, an exit rule),status,goal_reached,goal_id.
Users/subscriptions created by bulk import (CSV import) do not emit webhooks.
Body
{
"id": "whe_01J…",
"type": "delivery.clicked",
"created_at": "2026-10-07T12:00:00.000Z",
"app_id": "app_01J…",
"data": {
"delivery_id": "dlv_…",
"message_id": "msg_…",
"subscription_id": "sub_…",
"channel": "ios_push",
"user": { "id": "usr_…", "external_id": "u1" },
"button_id": "track"
}
}If a single event body exceeds 64 KB, { "truncated": true, "reason": "payload_too_large", "subject_id": … } is sent instead of data; read the details from the API.
Batch mode (endpoint setting batch: true): high-volume delivery.* events are sent in groups of 100 in a single request with a { "events": [ … ] } body; other events remain individual.
Headers
| Header | Description |
|---|---|
Pushizo-Signature | t=<unix seconds>,v1=<hex>; two v1 values during the rotation window |
Pushizo-Event-Id | Event ID (whe_…); does not change if the same event is resent (retry/replay) — use it to deduplicate |
Pushizo-Event-Type | Event type; batch for a batch body |
Pushizo-Batch-Id | Batch bodies only |
Pushizo-Delivery-Attempt | Attempt number (1–7) |
Custom headers you add to the endpoint (e.g. Authorization) are also sent; their values are stored encrypted and only their names are visible in the API.
Signature verification
v1 = HMAC-SHA256(secret, t + "." + raw_body) (hex). The receiver:
- Must use the raw body (do not parse and re-serialize the JSON).
- Must verify that
tis at most 5 minutes away from now — requests replayed with an oldtare rejected. - Must verify the signature with a constant-time comparison; it is valid if any of the
v1signatures in the header matches. - Must deduplicate with
Pushizo-Event-Idand return 2xx quickly (queue heavy work; the timeout is 10 s).
Node.js (@pushizo/node)
import express from 'express';
import { constructWebhookEvents, WebhookSignatureError } from '@pushizo/node';
const app = express();
app.post('/hooks/pushizo', express.raw({ type: 'application/json' }), (req, res) => {
try {
const events = constructWebhookEvents({
payload: req.body, // Buffer (raw body)
header: req.headers['pushizo-signature'],
secret: process.env.HS_WEBHOOK_SECRET!,
});
for (const event of events) enqueue(event); // deduplicate with Pushizo-Event-Id / event.id
res.sendStatus(204);
} catch (err) {
if (err instanceof WebhookSignatureError) return res.status(400).send(err.reason);
throw err;
}
});Without the SDK:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody: Buffer, header: string, secret: string, toleranceSec = 300): boolean {
const pairs = header.split(',').map((p) => p.split('=') as [string, string]);
const t = Number(pairs.find(([k]) => k === 't')?.[1]);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
return pairs
.filter(([k]) => k === 'v1')
.some(([, v]) => {
const sig = Buffer.from(v, 'hex');
return sig.length === expected.length && timingSafeEqual(sig, expected);
});
}PHP (pushizo/pushizo-php)
$payload = file_get_contents('php://input'); // raw body
$header = $_SERVER['HTTP_PUSHIZO_SIGNATURE'] ?? null;
try {
$events = Pushizo\Webhook::constructEvents($payload, $header, getenv('HS_WEBHOOK_SECRET'));
} catch (Pushizo\WebhookSignatureException $e) {
http_response_code(400);
exit($e->reason);
}
foreach ($events as $event) {
// deduplicate with $event['id']
}
http_response_code(204);Without the SDK: hash_hmac('sha256', $t . '.' . $payload, $secret) and hash_equals(); abs(time() - $t) <= 300.
The verification algorithm is tested with the same vectors in @pushizo/node (sdk/node/src/__tests__), the PHP SDK (sdk/php/tests/run.php) and the server (packages/webhooks); rejection of replays with an old t is covered by the tests.
Secret management
- The secret (
whsec_…) is shown only once, when the endpoint is created and on rotation; it can be viewed again in the dashboard with "Show" (this creates an audit record). On the server it is stored encrypted with envelope encryption. - Rotation (
POST …/webhooks/{id}/rotate-secret): the new secret is used immediately; the old secret continues to be sent as a secondv1signature for 24 hours. Move your receiver to the new secret within that window.
Retries, dead, replay
- A non-2xx response, a timeout (10 s), a network error or a redirect (3xx is not followed) counts as a failure.
- Backoff schedule: 1 min, 5 min, 30 min, 2 h, 6 h, 24 h. If the initial request + 6 retries (7 requests in total) fail, the delivery becomes
dead. - You can resend individually (
POST …/webhooks/deliveries/{id}/replay) or in bulk (POST …/webhooks/{id}/replay, failed/dead, at most 1000) from the dashboard or the API. A replay goes out with the samePushizo-Event-Id. - Endpoint health: if a streak of consecutive failures exceeds 7 days, the endpoint becomes
failingand an email is sent to the organization's owners/admins; if it exceeds 14 days, it becomesdisabledand pending deliveries are closed. After fixing the endpoint, enable it and bulk-replay the dead deliveries. Any successful delivery resets the streak. - Fair delivery: in each scan round, a limited number of deliveries is taken per endpoint, with at most 8 concurrent requests per endpoint. If a request to an endpoint fails, the remaining deliveries for it in that round are not sent; they are retried about 30 s later without counting as an attempt. This way, a slow or crashed receiver does not delay other endpoints.
- Multiple workers can safely run in parallel: a delivery is not sent if it cannot be completed within the claiming worker's lease (preventing the same delivery from being sent twice).
- Delivery records are kept for 30 days. Send test sends a
webhook.testevent immediately and shows the result (it is not retried).
Personal data (KVKK/GDPR)
- When a user is deleted (
DELETE /users/by/…), all webhook delivery records for that user (sent or pending; user, alias, tag/property, event and conversion payloads) are deleted; only auser.deletednotification is sent to the receiver. - The app's "Clear data" action also deletes the webhook delivery history (endpoint configuration is kept).
Monitoring
The webhook_deliveries_total{status}, webhook_delivery_latency_seconds (from event to successful delivery; SLO p95 < 30 s) and webhook_request_duration_seconds{outcome} metrics are published at /metrics. Local measurement: node tests/load/webhooks-bench.mjs --key … --app ….
Security (SSRF)
- Only
https://URLs are accepted; URLs with a username/password, local names such aslocalhost/.local/.internal, and private/reserved IP addresses are rejected. - At send time, the host name is resolved via DNS; if even one of the resolved addresses is private/reserved, no request is made, and the connection is pinned to the checked address (DNS rebinding protection).
- For local development, to test with a receiver on your own machine, you can set
WEBHOOK_ALLOW_INSECURE_TARGETS=truein.env(allows http and local addresses); this setting cannot be enabled whileNODE_ENV=production.