Skip to main content

Add Webhooks For Delivery Events

Use webhooks when your application needs to react to email delivery events without polling. Motorical can send events such as message.delivered, message.bounced, and message.complained to your HTTPS endpoint.

Flow​

Motorical delivery event -> signed webhook POST -> your app -> fast 2xx response

1. Mint a Public API Token​

Webhook management uses a short-lived bearer token with webhooks.manage.

curl -X POST "https://api.motorical.com/api/public/token/account-key" \
  -H "Authorization: ApiKey $AK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "motorBlockId": "YOUR_MOTOR_BLOCK_ID",
    "scopes": ["webhooks.manage", "logs.read", "analytics.read"],
    "ttlSeconds": 900
  }'

2. Create a Webhook​

curl -X POST "https://api.motorical.com/api/public/v1/motor-blocks/$BLOCK_ID/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/motorical",
    "events": ["message.delivered", "message.bounced", "message.complained"],
    "description": "production delivery events"
  }'

Store the webhook secret when it is returned. It is needed for signature verification.

3. Verify Signatures​

Verify X-Motorical-Signature with HMAC-SHA256 over the raw request body.

const crypto = require('crypto');

function verifyMotoricalWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'utf8'),
    Buffer.from(expected, 'utf8')
  );
}

Return a fast 2xx response, then process the event asynchronously.

4. Inspect Delivery History​

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.motorical.com/api/public/v1/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID/deliveries?limit=50"

5. Monitor Stats​

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.motorical.com/api/public/v1/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID/stats?hours=24"

Testing Notes​

A temporary webhook inspection service can help during manual testing, but production webhooks should point to an endpoint you control.

Use separate Motor Blocks for staging and production if you want webhook events, secrets, and delivery history isolated.