Skip to main content

Overview

Webhooks allow you to receive real-time notifications when events occur in your Sendook account. You can subscribe to events like receiving emails, delivery confirmations, bounces, and more.

Creating a Webhook

Set up a webhook by specifying your endpoint URL and the events you want to receive:
import Sendook from "@sendook/node";

const client = new Sendook("your_api_key");

await client.webhook.create({
  url: "https://your-app.com/webhooks/sendook",
  events: ["message.received", "message.delivered"]
});

Available Events

Subscribe to any of the following events:

Inbox Events

EventDescription
inbox.createdNew inbox was created
inbox.deletedInbox was deleted
inbox.updatedInbox details were updated

Message Events

EventDescription
message.sentMessage was sent to AWS SES
message.receivedIncoming email was received
message.deliveredMessage was successfully delivered to recipient
message.bouncedMessage bounced (invalid email or rejection)
message.complainedRecipient marked message as spam
message.rejectedMessage was rejected before sending
You can subscribe to multiple events in a single webhook by providing an array of event names.

Webhook Payload Structure

All webhooks follow this structure:
{
  "event": "message.received",
  "messageId": "msg_789",
  "inboxId": "inbox_123",
  "payload": {
    // Event-specific data
  }
}

Common Fields

FieldTypeDescription
eventstringThe event type that triggered the webhook
messageIdstringID of the related message (if applicable)
inboxIdstringID of the related inbox (if applicable)
payloadobjectEvent-specific data

Event Payload Examples

message.received

{
  "event": "message.received",
  "messageId": "msg_789",
  "inboxId": "inbox_123",
  "payload": {
    "id": "msg_789",
    "organizationId": "org_456",
    "inboxId": "inbox_123",
    "threadId": "thread_012",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Help with my account",
    "text": "I need help...",
    "html": "I need help...",
    "status": "received",
    "createdAt": "2024-01-01T12:00:00.000Z"
  }
}

message.delivered

{
  "event": "message.delivered",
  "messageId": "msg_456",
  "inboxId": "inbox_123",
  "payload": {
    "id": "msg_456",
    "organizationId": "org_456",
    "inboxId": "inbox_123",
    "threadId": "thread_012",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Welcome!",
    "status": "delivered",
    "createdAt": "2024-01-01T12:00:00.000Z",
    "updatedAt": "2024-01-01T12:05:00.000Z"
  }
}

message.bounced

{
  "event": "message.bounced",
  "messageId": "msg_456",
  "inboxId": "inbox_123",
  "payload": {
    "id": "msg_456",
    "status": "bounced",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Welcome!",
    // ... other message fields
  }
}

inbox.created

{
  "event": "inbox.created",
  "inboxId": "inbox_789",
  "payload": {
    "id": "inbox_789",
    "organizationId": "org_456",
    "name": "support",
    "email": "[email protected]",
    "createdAt": "2024-01-01T12:00:00.000Z"
  }
}

Managing Webhooks

List All Webhooks

const webhooks = await client.webhook.list();

console.log(webhooks);
// [
//   {
//     id: "webhook_123",
//     url: "https://your-app.com/webhooks/sendook",
//     events: ["message.received", "message.delivered"]
//   }
// ]

Get Webhook Details

const webhook = await client.webhook.get("webhook_123");

Delete a Webhook

await client.webhook.delete("webhook_123");

Testing Webhooks

Test your webhook endpoint to verify it’s working correctly:
await client.webhook.test("webhook_123");
// Sends a test message.received event to your endpoint
The test sends a message.received event with dummy data:
{
  "event": "message.received",
  "payload": {
    "test": "test"
  }
}

Implementing a Webhook Endpoint

Your webhook endpoint should:
  1. Accept POST requests
  2. Parse JSON body
  3. Process the event
  4. Respond with 2xx status code
import express from "express";

const app = express();

app.post("/webhooks/sendook", express.json(), async (req, res) => {
  try {
    const { event, messageId, inboxId, payload } = req.body;
    
    console.log(`Received webhook: ${event}`);
    
    // Handle different event types
    switch (event) {
      case "message.received":
        console.log(`New email from ${payload.from}`);
        // Process received email
        break;
        
      case "message.delivered":
        console.log(`Message ${messageId} delivered`);
        // Update delivery status in your database
        break;
        
      case "message.bounced":
        console.log(`Message ${messageId} bounced`);
        // Handle bounce (e.g., remove from mailing list)
        break;
        
      case "inbox.created":
        console.log(`New inbox: ${payload.email}`);
        break;
    }
    
    // Always respond with 200
    return res.status(200).json({ success: true });
  } catch (error) {
    console.error("Webhook error:", error);
    return res.status(500).json({ error: "Internal server error" });
  }
});

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});
Your webhook endpoint must respond within 5 seconds. For long-running operations, acknowledge the webhook immediately and process asynchronously.

Webhook Retry Logic

If your endpoint fails to respond with a 2xx status code:
  • Sendook will retry the webhook up to 3 times
  • Retries use exponential backoff (5s, 25s, 125s)
  • After 3 failed attempts, the webhook delivery is marked as failed
  • Repeated failures may result in your webhook being disabled
Monitor your webhook endpoint’s uptime and response times to ensure reliable event delivery.

Security Best Practices

Always use HTTPS URLs for webhook endpoints to ensure data is encrypted in transit.
In production, validate that requests are coming from Sendook’s servers by checking the source IP or implementing webhook signatures.
Store processed event IDs to prevent processing the same event multiple times if webhooks are retried.
Acknowledge webhooks within 5 seconds. Queue heavy processing for background jobs.
Set up alerts for webhook failures to catch issues early before webhooks are disabled.

Common Use Cases

Email Notification System

Use message.received to notify users of new emails in real-time.

Delivery Tracking

Monitor message.delivered and message.bounced to track email delivery rates.

Auto-Reply Bot

Respond to message.received events with automated replies.

Support Ticket Creation

Create support tickets automatically when receiving emails.

Next Steps

Receiving Emails

Learn more about handling incoming emails

Sending Emails

Understand message statuses and delivery

Threads

Track conversations with thread IDs

API Reference

View complete webhook API documentation

Build docs developers (and LLMs) love