Webhooks
Real-time, HMAC-signed notifications for every email event. Deliveries, bounces, opens, clicks, and complaints streamed to your endpoint with automatic retries.
Every email event, in real time
Subscribe to delivered, bounced, opened, clicked, and complained events — plus contact and domain events — and pick the exact set each endpoint receives. Events land at your endpoint within seconds.
HMAC-SHA256 signed payloads
Every request is signed with a per-endpoint secret you can rotate, so your endpoint can verify authenticity in a few lines of code — or one call to the SDK.
Retries and a replay tool
Failed deliveries retry with exponential backoff for up to 24 hours. Inspect the full delivery log and replay any event from the dashboard.
Verify a webhook
import { PostStack } from '@poststack.dev/sdk';
// rawBody must be the exact bytes we POSTed — parsing and
// re-serializing changes them and the signature won't match.
const ok = await PostStack.Webhooks.verify(
rawBody,
req.headers['x-poststack-signature'],
process.env.POSTSTACK_WEBHOOK_SECRET,
);
if (!ok) return res.status(401).json({ error: 'Invalid signature' });Use cases
Sync deliverability data into your warehouse
Stream every delivered, bounced, opened, clicked, and complained event into BigQuery, Snowflake, ClickHouse, or Postgres. Build cohort retention curves, content-performance dashboards, and ISP-level deliverability reports natively in your BI tool.
Update CRMs and CDPs in real time
Push email engagement signals into HubSpot, Salesforce, Customer.io, Segment, or Rudderstack. Your sales team sees "Alice opened the proposal" within seconds, not the next-day batch sync.
Trigger downstream automation
On `email.bounced` (hard bounce) automatically deactivate the user account; on `email.complained` open a support ticket; on `email.opened` advance a Customer Success playbook stage. Webhooks are the glue.
Build custom dashboards and alerts
Pipe events into Grafana, Datadog, or your own monitoring tool. Alert on sudden bounce-rate spikes, complaint thresholds, or unusual sending patterns before reputation damage starts.
How it works
Webhooks are HTTP POST requests delivered to a URL you control whenever an event occurs. PostStack emits email events (`email.sent`, `email.delivered`, `email.bounced`, `email.soft_bounced`, `email.opened`, `email.clicked`, `email.complained`, `email.unsubscribed`, `email.failed`, `email.suppressed`, `email.delivery_delayed`, `email.scheduled`, `email.inbound`), contact events (`contact.created`, `contact.updated`, `contact.deleted`, `contact.unsubscribed`) and domain events (`domain.created`, `domain.updated`, `domain.deleted`, `domain.verified`, `domain.failed`, `domain.dns_drift`). Each endpoint subscribes to exactly the event types you pick. Every request is signed with HMAC-SHA256 over the raw request body, using a per-endpoint secret you rotate from the dashboard. The signature is sent in the `X-PostStack-Signature` header as a comma-separated list of `sha256=…` elements — normally one, and two while a rotation grace window is open, so write your verifier to accept a list and match any element. Rotating a secret keeps the old one valid for a grace window (24 hours by default, up to 7 days, or 0 to cut over immediately) and signs every delivery with both, so you can ship the new secret without dropping the events in between. Payloads include the full email context — message ID, recipient, subject, tags, custom metadata — plus event-specific fields (bounce reason and RFC 3463 category, click URL, user agent, IP). Delivery retries with exponential backoff: 30s, 2m, 10m, 30m, 2h, 8h, 16h, giving up after roughly a day of attempts. Endpoints that permanently fail 20 deliveries in a row are auto-disabled, and the team owner gets an email plus a dashboard alert so you find out quickly. The dashboard shows full delivery history per endpoint with replay buttons for any individual event or batch — useful when you ship a bug, fix it, and want to re-process the events you missed.
Frequently asked questions
How do I verify a webhook is from PostStack?
Every request is signed with HMAC-SHA256 over the raw request body, using a per-endpoint secret you set in the dashboard. The signature is sent in `X-PostStack-Signature` as a comma-separated list of `sha256=<hex>` elements — accept the request if your secret matches any of them. Hash the exact bytes we sent (re-serializing a parsed body will not match), and compare in constant time. `PostStack.Webhooks.verify()` in the SDK does all of this for you.
What event types are supported?
Email events (sent, delivered, bounced and soft_bounced, opened, clicked, complained, unsubscribed, failed, suppressed, delivery_delayed, scheduled, inbound), contact events (created, updated, deleted, unsubscribed) and domain events (created, updated, deleted, verified, failed, dns_drift). Each endpoint subscribes to any subset.
What happens if my endpoint is down?
PostStack retries with exponential backoff (30s, 2m, 10m, 30m, 2h, 8h, 16h), giving up after about a day. After 20 deliveries in a row fail permanently the endpoint is auto-disabled, and you get an email plus a dashboard alert. You can re-enable and replay missed events from the dashboard.
Can I replay events?
Yes. Every delivery is logged with the request, response, and status. Replay any single delivery or a batch by date range with one click. Useful for catching up after deploying a fix.
Are there source IPs to allowlist?
Yes — PostStack webhook deliveries come from a small, documented set of EU IPs. Allowlist them in your firewall if your endpoint is locked down.