Webhooks

Receive real-time notifications when email events occur (delivered, bounced, opened, clicked).

Create a webhook

Terminal

curl -X POST https://send.grosend.com/api/v1/webhooks \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["delivered", "bounced", "opened", "clicked"]
  }'

Response

201 Created

{
  "id": "webhook-uuid",
  "url": "https://your-server.com/webhook",
  "events": ["delivered", "bounced", "opened", "clicked"],
  "secret": "whsec_...",
  "isActive": true,
  "createdAt": "2025-01-15T10:30:00Z"
}

Verifying signatures

Each webhook delivery includes a X-Grosend-Signature header with an HMAC-SHA256 signature of the request body using your webhook secret.

Node.js verification

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signature === expected;
}

Event payload

Webhook payload

{
  "event": "delivered",
  "emailId": "email-uuid",
  "to": "user@example.com",
  "timestamp": "2025-01-15T10:35:00Z",
  "metadata": {"order_id": "1234"}
}

Events

deliveredEmail successfully delivered to recipient

bouncedEmail bounced (hard or soft)

openedRecipient opened the email (tracking pixel)

clickedRecipient clicked a link (click tracking)

complainedRecipient marked as spam

Grosend retries failed webhook deliveries up to 5 times with exponential backoff. If your endpoint returns 5xx for all retries, the webhook is disabled.