Webhooks and Real-Time Email Event Tracking

Webhooks allow you to receive real-time notifications about email events. This enables you to build powerful integrations and automate workflows.

What Are Webhooks?

Webhooks are HTTP callbacks that OnePush sends to your server when email events occur. Instead of polling our API, you receive instant notifications.

Supported Events

OnePush sends webhooks for these events:

Email Sent

Triggered when an email is successfully queued for delivery.

Email Delivered

Fired when an email is successfully delivered to the recipient's mailbox.

Email Opened

Sent when a recipient opens your email (requires tracking to be enabled).

Link Clicked

Triggered when a recipient clicks a link in your email.

Bounce

Fired when an email bounces (hard or soft bounce).

Spam Complaint

Sent when a recipient marks your email as spam.

Unsubscribed

Triggered when a recipient unsubscribes from your emails.

Setting Up Webhooks

1. Create an Endpoint

Create a secure endpoint on your server that accepts POST requests:

app.post('/webhooks/onepush', async (req, res) => {
  const event = req.body;
  
  // Verify webhook signature
  const signature = req.headers['x-onepush-signature'];
  if (!verifySignature(signature, req.body)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Handle the event
  switch (event.type) {
    case 'email.delivered':
      await handleDelivery(event);
      break;
    case 'email.opened':
      await handleOpen(event);
      break;
    // ... other event types
  }
  
  res.status(200).send('OK');
});

2. Configure in Dashboard

Add your webhook URL in the OnePush dashboard. You can configure different endpoints for different event types.

3. Verify Signatures

Always verify webhook signatures to ensure requests are from OnePush:

function verifySignature(signature, payload) {
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  return signature === expectedSignature;
}

Use Cases

Update User Records

When an email bounces, mark the email address as invalid in your database.

Trigger Workflows

When a user opens a welcome email, trigger onboarding workflows in your application.

Analytics

Track email performance in real-time and update dashboards automatically.

Notifications

Send internal notifications when important emails fail to deliver.

Best Practices

• Always verify webhook signatures
• Handle events idempotently
• Respond quickly (within 5 seconds)
• Log all webhook events
• Set up retry logic for failed webhook deliveries

OnePush automatically retries failed webhook deliveries to ensure you never miss an event.