Skip to main content

​
What is a webhook?

Webhooks are HTTP callbacks that allow AutoSend to send real-time notifications to your application when specific events occur. Instead of continuously polling AutoSend’s API to check for updates, webhooks push data to your application immediately when events happen. AutoSend uses webhooks to push real-time notifications to your application about email and contact events. All webhooks use HTTPS and deliver a JSON payload that can be used by your application.

​
You can use webhooks to:

  • 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/retention
  • Trigger workflows when specific events occur (e.g., send Slack notification when email bounces)
  • Maintain compliance logs for audit purposes

​
How to create and setup webhooks

1

Create a local endpoint to receive requests

In your local application, create a new route that can accept 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");
});
On receiving an event, you should respond with an HTTP 200 OK status within 10 seconds to signal to AutoSend that the event was successfully delivered.
2

Register your development webhook endpoint

  1. Navigate to Webhooks from the AutoSend sidebar
  1. Click the “New Webhook” button
  2. Fill in the webhook details:
    • Name: A friendly name for identification (e.g., “Development Email Tracker”)
    • Endpoint URL: Your publicly accessible HTTPS URL (use your ngrok URL for development)
    • Events: Select the events you want to receive notifications for
  3. Click “Create Webhook”
  1. Important: Copy the secret token and save it securely - you’ll need it to verify webhook requests
After creating your webhook, the secret token will be displayed. Make sure to copy and save it securely. You can also reveal it later by editing the webhook and clicking “Reveal Secret”.
3

Test that your webhook endpoint is working properly

​
Monitor Your Endpoint

Start monitoring your local endpoint to see incoming webhook 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

Test your webhook by performing actions in AutoSend that trigger events:
  1. For Email Events: Send a test campaign or transactional email
  2. For Contact Events: Create, update, or delete a test contact in your project
  3. Watch your logs: Your endpoint should receive webhook requests for these events
4

Deploy your webhook endpoint

After testing locally, deploy your webhook endpoint to your production environment:
  • Vercel/Netlify: Deploy your API routes
  • AWS Lambda: Deploy as serverless function
  • Heroku/Railway: Deploy your application
  • Docker: Containerize and deploy to your infrastructure
Important: Ensure your production endpoint:
  • Uses HTTPS (required)
  • Responds within 10 seconds
  • Implements proper error handling
  • Verifies webhook signatures
5

Register your production webhook endpoint

Once deployed, create a new webhook in AutoSend with your production URL:
  1. Navigate to Webhooks from the AutoSend sidebar
  1. Click the “New Webhook” button
  2. Fill in the production details:
    • Name: “Production Email Tracker” (or any descriptive name)
    • Endpoint URL: Your production webhook URL (e.g., https://api.yourapp.com/webhooks/autosend)
    • Events: Select the events you want to track:
      • Email engagement: opened, clicked, unsubscribed
      • Deliverability: delivered, bounced, deferred
      • Contact events: created, updated, deleted
  3. Click “Create Webhook”
  1. Important: Copy the secret token and save it securely - you’ll need it to verify webhook requests
Copy and securely store the webhook secret
  • Store it as an environment variable: WEBHOOK_SECRET=your_secret_here
  • Never commit it to version control
  • Use a secret management service in production (AWS Secrets Manager, etc.)

​
Managing Your Webhooks

From the Webhooks page, you can:
  • View all webhooks for your project - displayed as cards showing webhook details
  • Edit webhooks - Click the menu (⋮) on a webhook card and select “Edit”
  • Delete webhooks - Click the menu (⋮) and select “Delete”
  • See webhook status - Each webhook shows “Enabled” or “Disabled” status
  • Copy webhook details - Webhook ID and URL are copyable from the card

​
Best Practices

Process webhooks asynchronously to 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.
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
});
Implement your own monitoring to track webhook delivery success/failure. The webhook model in AutoSend tracks failureCount, lastSuccessAt, and lastFailedAt which are updated automatically. 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 does not receive a 200 response from your webhook endpoint, we will automatically retry the delivery. 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. If you need to change the URL, delete the webhook and create a new one.
You can reveal your webhook secret:
  1. Navigate to Webhooks from the AutoSend sidebar
  2. Click the menu (⋮) on your webhook card
  3. Select “Edit”
  4. Click “Reveal Secret” button
  5. Copy and store it securely
AutoSend will retry failed deliveries up to 3 times with exponential backoff (1min, 5min, 15min). 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. Ensure your endpoint responds within this time.
Yes! Use tools like ngrok or localtunnel to expose your local server to the internet, then navigate to Webhooks from the AutoSend sidebar and create a webhook with your ngrok URL. Trigger events by sending emails or managing contacts in AutoSend, and your local endpoint will receive the webhooks.
Yes, all webhooks are sent over HTTPS and include an HMAC-SHA256 signature that you should verify. 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