Webhooks

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

Managing Webhooks

All webhook endpoints require the webhooks.manage scope.

List Webhooks

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks"

Response: Array of webhook endpoints with id, url, events, enabled, failure_count, last_delivery_at, and created_at.

Create a Webhook

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

If events is omitted, defaults to message.delivered, message.bounced, and message.complained.

Update a Webhook

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/new-url","enabled":true}' \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID"

Updatable fields: url, events (array), enabled (boolean).

Delete a Webhook

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID"

Test a Webhook

Send a test delivery to verify your endpoint is reachable:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID/test"

Returns 202 Accepted with a queued test delivery.

Delivery History

View recent webhook deliveries with status and latency:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID/deliveries?limit=50"

Parameters:

Parameter	Description
limit	Max deliveries to return (1–200, default 50)

Response: Array of deliveries with eventType, status, attempts, error, latencyMs, createdAt, and deliveredAt.

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