Webhooks Integration Guide

Receive real-time notifications when email events occur in your Motorical infrastructure.

Setting Up Webhooks

Create a Webhook Endpoint

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

Supported Events

Event	Trigger
message.delivered	Email delivered to recipient server
message.bounced	Email bounced (hard or soft)
message.complained	Recipient marked as spam
message.deferred	Delivery temporarily delayed
message.failed	Permanent delivery failure

Verifying Webhook Signatures

Every webhook POST includes an X-Motorical-Signature header containing an HMAC-SHA256 signature of the JSON body using your webhook secret.

Always verify this signature before processing:

const crypto = require('crypto');

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

Monitoring Webhook Health

Check delivery statistics for your webhook endpoints:

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

Best Practices

1. Respond quickly — Return 200 OK within 5 seconds
2. Process asynchronously — Queue payloads for background processing
3. Use HTTPS — All webhook URLs must use TLS
4. Verify signatures — Always check X-Motorical-Signature
5. Handle retries — Implement idempotency for duplicate deliveries
6. Monitor failures — Set up alerts for webhook delivery failures