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	Description
message.processed	Accepted by the gateway and handed to delivery — an intermediate event, not a final outcome
message.deferred	Delivery temporarily delayed; a retry is scheduled
message.delivered	Accepted by the recipient's server
message.bounced	Bounced (hard or soft)
message.failed	Permanent delivery failure
message.complained	Recipient marked the email as spam

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