​
Overview

Webhooks are HTTP callbacks that allow SendLayer to notify your application in real-time when specific email events occur. Instead of polling the API to check for updates, webhooks automatically send data to your specified URL when events happen, such as when an email is opened, clicked, or bounced.

​
How Webhooks Work

  1. Setup: You create a webhook by providing a URL endpoint and specifying which events you want to monitor
  2. Monitoring: SendLayer monitors your email activity for the specified events
  3. Notification: When an event occurs, SendLayer sends an HTTP POST request to your webhook URL with event data
  4. Processing: Your application receives and processes the webhook data

​
Prerequisites

​
Creating a Webhook

To create a webhook, you need to specify the event type you want to monitor and the URL where SendLayer should send notifications. 
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

const params = {
  url: 'https://your-domain.com/webhook',
  event: 'open'
};

const response = await sendlayer.Webhooks.create(params);
console.log('Webhook created with ID:', response.NewWebhookID);
Replace <apiKey> with your actual SendLayer API key in the request header.

​
Available Event Types

You can monitor the following email events:
EventDescription
deliveryEmail successfully delivered to recipient’s inbox
openRecipient opened the email
clickRecipient clicked a link in the email
bounceEmail failed to deliver and bounced back
unsubscribeRecipient unsubscribed from emails
complaintRecipient marked email as spam

​
Retrieving Webhooks

You can retrieve all webhooks associated with your account to see their current status and configuration. 
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

const webhooks = await sendlayer.Webhooks.get();
console.log('Webhooks:', webhooks.Webhooks);

​
Webhook Response Format

When you retrieve webhooks, you’ll receive data in this format: 
{
  "Webhooks": [
    {
      "WebhookID": "23718",
      "CreatedAt": "2025-04-11 09:43:07",
      "UpdatedAt": "2025-04-11 09:43:07",
      "Status": "Enabled",
      "WebhookURL": "https://your-domain.com/webhook",
      "Event": "open",
      "LastResponseCode": "200",
      "LastResponseBody": "",
      "LastResponseAt": "2025-04-11 10:15:30",
      "LastResponseTryCounter": "0"
    }
  ]
}

​
Deleting a Webhook

You can delete a webhook by providing its ID. This action cannot be undone. 
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

const webhookId = 23718;
await sendlayer.Webhooks.delete(webhookId);
console.log('Webhook deleted successfully');
Deleting a webhook cannot be undone. You won’t be able to recover or access your webhook after deleting it.

​
Webhook Payload Format

When SendLayer sends a webhook notification to your endpoint, it includes detailed information about the event. Here’s an example of what you might receive: 
{
  "Event": "open",
  "LoggedAt": 1746340896,
  "LogLevel": "info",
  "Message": {
    "Headers": {
      "MessageId": "06e4491f-fc5a-49cb-bc57-xxxxxx",
      "From": [["", "sender@example.com"]],
      "ReplyTo": [],
      "To": [["", "recipient@example.com"]],
      "Cc": [],
      "Bcc": []
    },
    "Size": 2004,
    "Transport": "api"
  },
  "Recipient": "recipient@example.com",
  "Reason": "Email opened.",
  "Ip": "10.30.126.18",
  "Geolocation": {
    "City": "San Francisco",
    "Region": "CA",
    "Country": "US"
  }
}

​
Best Practices

  1. Use HTTPS: Always use HTTPS URLs for your webhook endpoints to ensure data security
  2. Validate Signatures: Consider implementing signature validation to verify webhook authenticity
  3. Monitor Status: Regularly check your webhook status and response codes
  4. Error Handling: Implement proper error handling for webhook processing

​
FAQ