Webhooks

Receive real-time notifications when events happen in your account. Webhooks allow your application to react to email deliveries, SMS status updates, call events, and more.

How It Works

Configure Endpoint

Set up a URL to receive webhook events

Events Trigger

We send POST requests when events occur

Process & Respond

Handle the event and return 200 OK

Available Events

Email Events

email.sentEmail was successfully sent

email.deliveredEmail was delivered to recipient

email.openedRecipient opened the email

email.clickedRecipient clicked a link

email.bouncedEmail bounced (hard/soft)

email.complainedRecipient marked as spam

SMS Events

sms.sentSMS was sent to carrier

sms.deliveredSMS was delivered

sms.failedSMS delivery failed

sms.receivedIncoming SMS received

Voice Events

call.initiatedCall was initiated

call.answeredCall was answered

call.completedCall ended

call.failedCall failed to connect

Payload Example

JSON

{
  "id": "evt_1234567890",
  "type": "email.delivered",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "message_id": "msg_abcdef123456",
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Welcome!",
    "delivered_at": "2024-01-15T10:30:00Z"
  }
}

Signature Verification

Always Verify Signatures

Verify the webhook signature to ensure requests come from EKDSend and haven't been tampered with.

JavaScript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from('sha256=' + expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-ekdsend-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Event:', req.body.type);
  res.status(200).send('OK');
});

Best Practices

Respond Quickly

Return 200 OK within 5 seconds. Process async if needed.

Handle Retries

We retry failed webhooks up to 5 times with exponential backoff.

Use HTTPS

Always use HTTPS endpoints for webhook URLs.