Webhooks and Real-Time Email Event Tracking

Webhooks tell your app what happened after POST /v1/send: delivered, opened, clicked, bounced, complained. Without them you are guessing from a dashboard.

Why webhooks beat polling

Polling logs every minute burns quota and still lags. A webhook posts the event when it happens so you can suppress bad addresses, unlock accounts after delivery, or alert on spam complaints in near real time.

Events you should handle

At minimum wire handlers for:

• delivered
• bounced (hard vs soft if the payload distinguishes them)
• complained / spam report
• opened and clicked if you use engagement data carefully (opens are noisy)

Exact event names and payload fields are documented in the API reference. Treat unknown event types as no-ops so new events do not crash your endpoint.

Endpoint sketch (Express)

import express from 'express';
import crypto from 'crypto';

const app = express();
app.post('/webhooks/onepush', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.header('X-OnePush-Signature'); // confirm header name in docs
  // Verify signature before trusting the body
  const event = JSON.parse(req.body.toString('utf8'));

  switch (event.type) {
    case 'bounced':
      // suppress address, mark contact invalid
      break;
    case 'complained':
      // stop optional mail, review content
      break;
    case 'delivered':
      // optional: mark "reset email delivered" in your DB
      break;
    default:
      break;
  }

  res.status(200).send('ok');
});

Return 2xx quickly. Do heavy work async. If your endpoint times out, providers retry and you will see duplicates. Make handlers idempotent using the event id.

Signature verification

Always verify the webhook signature with your project secret. Reject requests that fail verification. Do not process unsigned payloads in production.

Product use cases

• Auto-suppress hard bounces before the next campaign
• Show "email delivered" in support tooling
• Page on-call when complaint rate spikes
• Feed analytics into your own warehouse

For dashboard-side monitoring patterns, see email analytics.

Setup checklist

1. Create an HTTPS endpoint
2. Add the webhook URL in the OnePush dashboard
3. Verify signatures
4. Handle bounces and complaints before opens/clicks
5. Log raw payloads for a week while you validate the schema

Plans that include webhooks and event logs start on Starter at $20/month.