PushizoDocs
Webhooks

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

GroupEvents
Messagemessage.queued, message.completed, message.failed
Deliverydelivery.sent, delivery.delivered, delivery.failed, delivery.opened, delivery.clicked, delivery.bounced, delivery.complained, delivery.unsubscribed
In-appin_app.impression, in_app.clicked (button_id), in_app.dismissed
Subscriptionsubscription.created, subscription.unsubscribed, subscription.invalidated
Useruser.created, user.updated, user.merged, user.deleted
Eventevent.received (an event name filter is required: event_filters.event_names, at least one name)
Conversionconversion.created
Campaigncampaign.scheduled, campaign.started, campaign.completed
Journeyjourney.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.completed and journey.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

HeaderDescription
Pushizo-Signaturet=<unix seconds>,v1=<hex>; two v1 values during the rotation window
Pushizo-Event-IdEvent ID (whe_…); does not change if the same event is resent (retry/replay) — use it to deduplicate
Pushizo-Event-TypeEvent type; batch for a batch body
Pushizo-Batch-IdBatch bodies only
Pushizo-Delivery-AttemptAttempt 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:

  1. Must use the raw body (do not parse and re-serialize the JSON).
  2. Must verify that t is at most 5 minutes away from now — requests replayed with an old t are rejected.
  3. Must verify the signature with a constant-time comparison; it is valid if any of the v1 signatures in the header matches.
  4. Must deduplicate with Pushizo-Event-Id and 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 second v1 signature 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 same Pushizo-Event-Id.
  • Endpoint health: if a streak of consecutive failures exceeds 7 days, the endpoint becomes failing and an email is sent to the organization's owners/admins; if it exceeds 14 days, it becomes disabled and 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.test event 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 a user.deleted notification 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 as localhost/.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=true in .env (allows http and local addresses); this setting cannot be enabled while NODE_ENV=production.

On this page