Webhooks

Motorical can push real-time notifications to your server when email events occur — deliveries, bounces, complaints, and more.

Creating a Webhook

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhook","events":["message.delivered"]}' \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks"

Scopes required: webhooks.manage

Signature Verification

Every webhook POST is signed with X-Motorical-Signature — an HMAC-SHA256 of the JSON body using your secret. Always verify this signature before processing the payload.

const crypto = require('crypto');

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

Available Events

Event	Description
message.delivered	Email successfully delivered to recipient's server
message.bounced	Email bounced (hard or soft bounce)
message.complained	Recipient marked the email as spam
message.deferred	Delivery temporarily delayed
message.failed	Permanent delivery failure

Monitoring Webhook Health

Check delivery statistics for a webhook endpoint:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID/stats?hours=24"

Response includes: delivered count, failed count, queued count, failure rate, and average latency.

Best Practices

• Respond quickly — return 200 OK within 5 seconds
• Process asynchronously — queue webhook payloads for background processing
• Verify signatures — always validate X-Motorical-Signature
• Handle retries — Motorical retries failed deliveries with exponential backoff
• Use HTTPS — webhook URLs must use TLS