Webhooks API

Create, manage, and configure webhooks to receive real-time notifications for email events.

List Webhooks

Get all webhooks configured for your organization.

Endpoint


GET /api/webhooks

Example Request


curl -X GET NEXT_PUBLIC_BASE_URL/api/webhooks \
  -H "x-api-key: your-api-key"

Response Schema

Field	Type	Description
`id`	`string`	Webhook unique identifier
`url`	`string`	Destination URL for webhook payloads
`events`	`string[]`	List of subscribed events
`secret`	`string`	HMAC signing secret (32 characters)
`isActive`	`boolean`	Whether the webhook is active
`organizationId`	`string`	Organization identifier
`createdAt`	`string`	ISO 8601 creation timestamp
`updatedAt`	`string`	ISO 8601 last update timestamp

Example Response


[
  {
    "id": "wh_abc123",
    "url": "https://example.com/webhooks/mailpulse",
    "events": ["EMAIL_SENT", "EMAIL_OPENED"],
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "isActive": true,
    "organizationId": "org_xyz789",
    "createdAt": "2024-03-10T14:00:00.000Z",
    "updatedAt": "2024-03-10T14:00:00.000Z"
  }
]

Create Webhook

Endpoint


POST /api/webhooks

Request Body

Field	Type	Required	Description
`url`	`string`	Yes	Destination URL (must be HTTPS)
`events`	`string[]`	Yes	Events to subscribe to

Available events: EMAIL_SENT, EMAIL_OPENED, EMAIL_CLICKED.

Example Request


curl -X POST NEXT_PUBLIC_BASE_URL/api/webhooks \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/mailpulse",
    "events": ["EMAIL_SENT", "EMAIL_OPENED", "EMAIL_CLICKED"]
  }'

Example Response


{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/mailpulse",
  "events": ["EMAIL_SENT", "EMAIL_OPENED", "EMAIL_CLICKED"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "isActive": true,
  "organizationId": "org_xyz789",
  "createdAt": "2024-03-10T14:00:00.000Z",
  "updatedAt": "2024-03-10T14:00:00.000Z"
}

Update Webhook

Update an existing webhook’s URL, events, or active status.

Endpoint


PATCH /api/webhooks/:id

Path Parameters

Parameter	Type	Description
`id`	`string`	Webhook ID

Request Body

Field	Type	Required	Description
`url`	`string`	No	New destination URL
`events`	`string[]`	No	Updated event list
`isActive`	`boolean`	No	Enable or disable the webhook

Example Request


curl -X PATCH NEXT_PUBLIC_BASE_URL/api/webhooks/wh_abc123 \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["EMAIL_OPENED"],
    "isActive": false
  }'

Example Response


{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/mailpulse",
  "events": ["EMAIL_OPENED"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "isActive": false,
  "organizationId": "org_xyz789",
  "createdAt": "2024-03-10T14:00:00.000Z",
  "updatedAt": "2024-03-12T09:15:00.000Z"
}

Delete Webhook

Remove a webhook from your organization.

Endpoint


DELETE /api/webhooks/:id

Path Parameters

Parameter	Type	Description
`id`	`string`	Webhook ID

Example Request


curl -X DELETE NEXT_PUBLIC_BASE_URL/api/webhooks/wh_abc123 \
  -H "x-api-key: your-api-key"

Example Response


{
  "success": true
}

Signature Verification

Every webhook request includes an HMAC-SHA256 signature in the x-webhook-signature header. Use the secret from your webhook object to verify the payload authenticity.

Verification Example (Node.js)


import crypto from "crypto";
 
function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Error Responses

Status	Description
`401 Unauthorized`	Invalid or missing API key
`404 Not Found`	Webhook not found or doesn’t belong to your organization

Example Error


{
  "error": "Unauthorized"
}