Skip to main content

​
What is a webhook?

Webhooks are HTTP callbacks that send real-time notifications to your application when specific events occur. Instead of continuously polling the AutoSend API to check for updates, webhooks push data to your application the moment events happen. All AutoSend webhooks use HTTPS and deliver a JSON payload that your application can process immediately.

​
Why use webhooks? Common use cases:

  • Automatically remove bounced email addresses from your mailing lists
  • Track email engagement in real-time (opens, clicks, unsubscribes)
  • Sync contact changes across multiple systems
  • Create alerts in your messaging or incident tools based on event types
  • Store all events in your own database for custom reporting and retention
  • Trigger workflows when specific events occur (e.g., send a Slack notification when an email bounces)
  • Maintain compliance logs for audit purposes

​
How to set up webhooks

1

Create a local endpoint to receive requests

Create a new route in your application that accepts POST requests.
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhooks/autosend', (req, res) => {
  // Verify signature (see Verify Webhook Requests section)
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifySignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook
  const { event, data } = req.body;
  console.log(`Received ${event} event:`, data);

  // Process based on event type
  switch (event) {
    case 'email.opened':
      // Handle email opened
      break;
    case 'email.clicked':
      // Handle email clicked
      break;
    case 'contact.created':
      // Handle contact created
      break;
    // ... handle other events
  }

  // Always respond quickly with 2xx status
  res.status(200).json({ received: true });
});

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

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});
When you receive an event, respond with an HTTP 200 OK status within 10 seconds to confirm successful delivery.
2

Register your webhook endpoint

  1. Go to Webhooks in the AutoSend sidebar
  1. Click “New Webhook”
  2. Fill in the webhook details:
    • Name: A friendly name for identification (e.g., “Production Email Tracker”)
    • Endpoint URL: Your publicly accessible HTTPS URL. For local development, use a tunneling service like ngrok or localtunnel.
    • Events: Select the events you want to receive notifications for
  3. Click “Create Webhook”
  1. Copy the secret token and store it securely. You’ll need it to verify webhook requests.
Store your webhook secret as an environment variable (WEBHOOK_SECRET=your_secret_here). Never commit it to version control. In production, use a secret management service like AWS Secrets Manager.
3

Test your webhook

Add logging to your endpoint to verify incoming requests:
app.post('/webhooks/autosend', (req, res) => {
  console.log('Webhook received!');
  console.log('Event:', req.body.event);
  console.log('Data:', JSON.stringify(req.body.data, null, 2));
  res.status(200).json({ received: true });
});
Trigger test events by performing actions in AutoSend:
  • For email events: Send a test campaign or transactional email
  • For contact events: Create, update, or delete a test contact
Watch your logs to confirm your endpoint receives the webhook requests.
4

Deploy to production

After testing locally, deploy your webhook endpoint to your production environment (Vercel, Netlify, AWS Lambda, Railway, etc.).Your production endpoint must:
  • Use HTTPS (required)
  • Respond within 10 seconds
  • Implement proper error handling
  • Verify webhook signatures
Once deployed, create a new webhook in AutoSend with your production URL. If you used a tunneling URL for development, you’ll need to register a separate webhook for production.

​
Managing webhooks

From the Webhooks page, you can:
  • View all webhooks for your project, displayed as cards with webhook details
  • Edit webhooks: Click the menu (⋮) on a webhook card and select “Edit”
  • Delete webhooks: Click the menu (⋮) and select “Delete”
  • Check webhook status: Each card shows whether the webhook is “Enabled” or “Disabled”
  • Copy webhook details: The webhook ID and URL are copyable from each card
If you lose your webhook secret, you can reveal it by editing the webhook and clicking “Reveal Secret”.

​
Best practices

Process webhooks asynchronously so you can respond within 10 seconds:
// ❌ Bad: Synchronous processing
app.post("/webhooks/autosend", async (req, res) => {
  await updateDatabase(data);
  await sendToAnalytics(data);
  res.status(200).json({ received: true });
});

// ✅ Good: Asynchronous processing
app.post("/webhooks/autosend", async (req, res) => {
  // Queue for background processing
  await queue.add("process-webhook", { event, data });

  // Respond immediately
  res.status(200).json({ received: true });
});
Never trust incoming webhook requests without verification. See the Verify Webhook Requests guide for implementation details.
Maintain detailed logs for debugging:
app.post("/webhooks/autosend", (req, res) => {
  logger.info(
    {
      deliveryId: req.headers["x-webhook-delivery-id"],
      event: req.body.event,
      timestamp: new Date().toISOString(),
    },
    "Webhook received"
  );

  // Process webhook
});
Track webhook delivery success and failure rates. AutoSend automatically tracks failureCount, lastSuccessAt, and lastFailedAt for each webhook. See Retries and Replays for monitoring examples.

​
FAQ

AutoSend supports email engagement events (opened, clicked, bounced, delivered, etc.) and contact events (created, updated, deleted). See the Event Types guide for the complete list.
If AutoSend doesn’t receive a 200 response from your webhook endpoint, it automatically retries delivery up to 3 times with exponential backoff (1 min, 5 min, 15 min). See Retries and Replays for details.
Yes, you can create up to 100 webhooks per project. Each webhook can subscribe to different events and point to different endpoints.
No, webhook URLs cannot be changed after creation for security reasons. To use a different URL, delete the existing webhook and create a new one.
AutoSend retries failed deliveries up to 3 times with exponential backoff. After all retries are exhausted, the delivery is marked as failed. See the Retries and Replays guide for details.
Yes, webhook requests have a 10-second timeout. Make sure your endpoint responds within this window.
Use tools like ngrok or localtunnel to expose your local server to the internet. Create a webhook in AutoSend with your tunnel URL, then trigger events by sending emails or managing contacts.
Yes, all webhooks are sent over HTTPS and include an HMAC-SHA256 signature for verification. See Verify Webhook Requests for implementation details.

Event Types

Complete list of webhook events and payloads

Retries and Replays

Automatic retry logic and best practices

Verify Webhook Requests

Security and signature verification

Webhooks

Manage your webhooks from the AutoSend sidebar