Webhooks

Events to your own endpoint.

Subscribe an endpoint to any of seven events and get a signed JSON request for each. Webhook delivery is newly wired: it carries no delivery-time commitment, and an event that fails all 5 attempts is not sent again.

Webhook endpoints are on the Pro, Business and Enterprise plans, or with a PostFrame add-on from Growth up.

The events, one by one.

Seven events can fire on a subscription. Each has its own page with the fields it carries.

Webhook events and the fields they add
EventWhen it is sentFields added to data
email.deliveredAmazon SES reports the receiving server accepted the message.smtp_response, processing_time_ms, timestamp, provider
email.openedThe tracking pixel loads.ip, user_agent
email.clickedA tracked link is clicked.url, ip, user_agent
email.bouncedAmazon SES reports a bounce.bounce_type, bounce_sub_type, ses_bounce_type, timestamp, diagnostic_code, provider
email.complainedAmazon SES reports a spam complaint.complaint_feedback_type, timestamp, provider
email.unsubscribedA recipient unsubscribes.method, ip
email.failedNo provider is available, the template is missing, or every provider fails.reason, and the failed attempts when providers were tried

Every event also carries email_id, message_id, from, to, subject, status, tags, created_at. The endpoint form lists deferred as well, but no deferred event is sent today: delivery-delay notices are logged without a webhook. The sent event is written to the log and cannot be subscribed to, and queued is not emitted. Delivered, bounced and complained events come from Amazon SES notifications, so sends through another connected provider do not produce them yet.

What a request looks like.

  • A JSON body with the event name, a Unix timestamp and a data object.
  • The signature and the timestamp travel in headers, so you can check a request before you parse it.
  • Each attempt waits up to 10 seconds for your answer. Redirects are not followed.
  • Endpoint URLs on private networks are refused when you save them.
An email.opened request. Angle brackets mark placeholders.
POST <your endpoint url>
Content-Type: application/json
X-PostFrame-Event: email.opened
X-PostFrame-Timestamp: <unix seconds>
X-PostFrame-Signature: v1=<hex>

{
  "event": "email.opened",
  "timestamp": <unix seconds>,
  "data": {
    "email_id": "<uuid>",
    "message_id": "<message id>",
    "from": "<sender address>",
    "to": [{ "email": "<recipient address>" }],
    "subject": "<subject>",
    "status": "opened",
    "tags": [],
    "created_at": "<ISO time>",
    "ip": "<ip address>",
    "user_agent": "<client string>"
  }
}

Check the signature.

The signature is an HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the endpoint's signing secret. Compare it in constant time. The Node and Python snippets shown in the dashboard check this same scheme. The signing secret can be rotated through the API.

Verification in Node.
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body exactly as received. secret: the endpoint's signing secret.
export function isFromPostFrame(rawBody, headers, secret) {
  const timestamp = headers['x-postframe-timestamp'];
  const received = String(headers['x-postframe-signature'] ?? '').replace(/^v1=/, '');
  const expected = createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex');
  const a = Buffer.from(received, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

When your endpoint is down

Signed payloads, up to four retries with exponential backoff, a delivery log per endpoint, a test button in the dashboard, and secret rotation through the API.

A failed delivery is retried up to four times, waiting 10, 20, 40 and 80 seconds. The delivery log keeps one entry per delivery, with the event type, the last HTTP status, the attempt number and the timing. After the last attempt the event is not sent again, and the failed entry stays in the log. The Test action sends a test event to your URL.

How do I verify a webhook came from PostFrame?

Read X-PostFrame-Signature (v1=<hex>) and X-PostFrame-Timestamp, then recompute HMAC-SHA256 over "<timestamp>.<body>" with the endpoint's signing secret, using the body exactly as received. Compare in constant time. The Node and Python snippets shown in the dashboard check this same scheme.

What happens if my endpoint is down?

PostFrame retries a failed delivery up to 4 times, waiting 10, 20, 40 and 80 seconds, and the endpoint's delivery log keeps one entry per delivery with the event type, last HTTP status, timing and attempt number. After the last attempt the event is not sent again.

Is webhook delivery guaranteed?

No. Webhook delivery is newly wired and carries no delivery or timing commitment. An event is attempted up to 5 times; if every attempt fails it is not sent again, and the failed entry stays in the delivery log.

Which events can I subscribe to?

Any of seven: delivered, opened, clicked, bounced, complained, unsubscribed and failed. Pick them per endpoint and change the list later without recreating it. The form also lists deferred, but no deferred event is sent today. Sent is logged but cannot be subscribed to, and queued is not emitted.

Do test emails fire webhooks?

No. Emails sent in test mode, for example with a pf_test_ API key, never dispatch webhooks. Use the endpoint's Test action to send a test event instead.

Run your business from one place.

Five plans, 25 launch apps, one dashboard. Change tiers any time.

From $0 · Basic $9.95/mo · Upgrade or downgrade any time