​
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);

​
Get 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. Below, we’ve provided examples of the payload for each event: 
{
  "event": {
    "method": "POST",
    "path": "/",
    "query": {},
    "client_ip": "0.0.0.0",
    "url": "https://your-domain.com/webhook",
    "headers": {
      "host": "your-domain.com",
      "content-length": 320,
      "user-agent": "GuzzleHttp/6.5.1 curl/7.68.0 PHP/5.6.40-67+ubuntu20.04.1+deb.sury.org+1",
      "content-type": "application/json"
    },
    "body": {
      "Signature": {
        "Timestamp": 1758100959,
        "Token": "c0a6c82bdde01faab7e857",
        "Signature": "3d1bf89405e4b71ed80bc240cd512aa7ed9db9dcfb17"
      },
      "EventData": {
        "Event": "opened",
        "Domain": "example.com",
        "MessageID": "4331c06-2d1d-4387-969e-697835",
        "To": "recipient@example.com",
        "IPAddress": "10.30.126.18"
      }
    }
  }
}

​
Best Practices

  1. Use HTTPs: Always use HTTPs URLs for your webhook endpoints to ensure data security
  2. Monitor Status: Regularly check your webhook status and response codes
  3. Error Handling: Implement proper error handling for webhook processing

​
FAQs

You can create multiple webhooks for different events and endpoints. There’s no strict limit, but it’s recommended to keep the number manageable for easier maintenance.
SendLayer will retry sending webhook notifications if your endpoint is unavailable. Check the LastResponseCode and LastResponseTryCounter fields to monitor delivery status.
Currently, webhooks cannot be updated. You’ll need to delete the existing webhook and create a new one with the updated configuration.
You can use tools like webhook.site or ngrok to create temporary public URLs for testing webhook functionality during development.
Check your webhook endpoint’s availability, verify the URL is correct, and ensure your server can handle POST requests. Review the LastResponseCode field for error details.