Create Webhook

curl --request POST \
  --url https://api.example.com/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    "<string>"
  ]
}
'

import requests

url = "https://api.example.com/webhooks"

payload = {
    "url": "<string>",
    "events": ["<string>"]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({url: '<string>', events: ['<string>']})
};

fetch('https://api.example.com/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'events' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"events\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/webhooks")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"events\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"events\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "webhook": {},
  "signing_key": "<string>"
}

Create Webhook

curl --request POST \
  --url https://api.example.com/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    "<string>"
  ]
}
'

import requests

url = "https://api.example.com/webhooks"

payload = {
    "url": "<string>",
    "events": ["<string>"]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({url: '<string>', events: ['<string>']})
};

fetch('https://api.example.com/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'events' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"events\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/webhooks")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"events\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"events\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "webhook": {},
  "signing_key": "<string>"
}

Description

Create a webhook to receive real-time notifications of Sendly events.

Parameters

url

string

required

HTTPS URL where to receive notifications. Example: https://yourdomain.com/webhooks/sendly

events

string[]

required

Array of events to receive.Available events:

email.sent: Email was sent
email.delivered: Email was delivered
email.bounced: Email bounced
email.failed: Send failed
email.opened: Email was opened
email.clicked: Link was clicked

Response

webhook

object

Created webhook object with id, url, active, created_at

signing_key

string

Secret key for validating webhooks. Save this securely!

Examples

curl -X POST https://api.usesendly.app/v1/webhooks \
  -H "Authorization: Bearer se_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourdomain.com/webhooks/sendly",
    "events": [
      "email.delivered",
      "email.bounced",
      "email.opened",
      "email.clicked"
    ]
  }'

const webhook = await client.webhooks.create({
  url: 'https://yourdomain.com/webhooks/sendly',
  events: [
    'email.delivered',
    'email.bounced',
    'email.opened',
    'email.clicked'
  ]
})

console.log('Webhook ID:', webhook.webhook.id)
console.log('Signing key:', webhook.signing_key)

import { Sendly } from '@sendlyapp/sdk'

const client = new Sendly()
const webhook = await client.webhooks.create({
  url: 'https://yourdomain.com/webhooks/sendly',
  events: ['email.delivered', 'email.bounced']
})

Validate Webhook Signature

import crypto from 'crypto'
import express from 'express'

const app = express()
const WEBHOOK_SECRET = 'your_signing_key'

function validateWebhookSignature(payload, signature) {
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex')
  
  return hash === signature
}

app.post('/webhooks/sendly', (req, res) => {
  const signature = req.headers['x-sendly-signature']
  
  if (!validateWebhookSignature(req.body, signature)) {
    return res.status(401).send('Invalid signature')
  }
  
  // Process webhook event
  handleEvent(req.body)
  
  res.send('OK')
})

function handleEvent(event) {
  console.log(`Event: ${event.type}`)
  
  switch (event.type) {
    case 'email.delivered':
      console.log(`Email delivered: ${event.data.email_id}`)
      break
    case 'email.opened':
      console.log(`Email opened: ${event.data.email_id}`)
      break
  }
}

from flask import Flask, request
import hmac
import hashlib
import json

app = Flask(__name__)
WEBHOOK_SECRET = b'your_signing_key'

def validate_webhook(payload, signature):
    hash_obj = hmac.new(WEBHOOK_SECRET, payload, hashlib.sha256)
    return hash_obj.hexdigest() == signature

@app.route('/webhooks/sendly', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Sendly-Signature')
    payload = request.get_data()
    
    if not validate_webhook(payload, signature):
        return 'Invalid signature', 401
    
    event = json.loads(payload)
    print(f"Event: {event['type']}")
    
    return 'OK', 200

Webhook Events

email.delivered

{
  "type": "email.delivered",
  "data": {
    "email_id": "email_123",
    "to": "user@example.com",
    "subject": "Subject",
    "delivered_at": "2024-01-15T10:30:00Z"
  }
}

email.opened

{
  "type": "email.opened",
  "data": {
    "email_id": "email_123",
    "to": "user@example.com",
    "opened_at": "2024-01-15T11:00:00Z",
    "user_agent": "Mozilla/5.0..."
  }
}

email.clicked

{
  "type": "email.clicked",
  "data": {
    "email_id": "email_123",
    "to": "user@example.com",
    "url": "https://example.com",
    "clicked_at": "2024-01-15T11:05:00Z"
  }
}

Retries

If your webhook returns non-2xx status, Sendly will retry:

1st: 5 minutes later
2nd: 30 minutes later
3rd: 2 hours later
4th: 24 hours later

Best Practices

✅ Always validate the x-sendly-signature header ✅ Respond quickly (< 30 seconds) ✅ Use HTTPS required ✅ Store key securely in environment variables ✅ Log events for audit trail ✅ Handle idempotence - process each event once

Need help? Contact support@usesendly.app

List Webhooks Get Webhook

​Description

​Parameters

​Response

​Examples

​Validate Webhook Signature

​Webhook Events

​email.delivered

​email.opened

​email.clicked

​Retries

​Best Practices