Webhooks

Webhooks

Configure your account to receive real-time notifications when important events occur.

Setting Up Webhooks

1. Go to Settings → API Access
2. Under Webhook URL, enter your endpoint
3. Click Save
4. Verify signature in your receiver (see Signature Verification below)

Webhook Events

Webhook Payload

{
  "event": "alert.created",
  "timestamp": "2026-08-06T21:32:00Z",
  "data": {
    "alert_id": 12345,
    "domain": "example.com",
    "severity": "high",
    "title": "SPF Policy Not Found"
  }
}

Signature Verification

Every webhook includes an X-Webhook-Signature header containing an HMAC SHA-256 hash. Verify it like this:

// Node.js example
const crypto = require('crypto');
const signature = req.headers['x-webhook-signature'];
const body = req.rawBody; // Raw request body
const secret = process.env.DMARC_BUSTA_WEBHOOK_SECRET;

const hash = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

if (hash !== signature) {
  return res.status(401).send('Unauthorized');
}

Retry Policy

If your endpoint returns an error (5xx or timeout), we'll retry with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: 5 seconds
• Attempt 3: 30 seconds
• Attempt 4: 5 minutes
• Attempt 5: 1 hour

Authentication Methods

DMARC Busta supports multiple authentication methods depending on your use case.

1. Bearer Token (API)

For programmatic access to the API.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.dmarcbusta.com/api/v1/domains

• Create tokens in Settings → API Access
• Each token is scoped to the creating user's account
• Store securely — never commit to repositories
• Revoke unused tokens anytime

2. Session-Based (Web)

Browser-based authentication for the web dashboard.

• Login with email/password, Google, Azure, or LinkedIn
• Session stored in secure HTTP-only cookies
• CSRF protection enabled
• Automatic logout after 30 days of inactivity

3. Embed Key (Widgets)

For third-party embedded scanners and widgets.

// Embed endpoint
GET /api/embed/{embed_key}/scan

• Public-key authentication (no secret required)
• CORS validation on origin domain
• Used for whitelabel widgets

4. Webhook Signatures

For verifying inbound webhook events.

• X-Webhook-Signature header contains HMAC SHA-256 hash
• Verify with your webhook secret from Settings → API Access
• Replay attacks prevented via timestamp validation

5. OAuth (Social Login)

Supported providers for account authentication:

• Google OAuth 2.0
• Microsoft Azure AD
• LinkedIn OAuth

Rate Limiting

API rate limiting prevents abuse and ensures fair usage across all accounts.

Default Limits

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1691350320

Handling Rate Limits

When you hit a rate limit, the API returns 429 Too Many Requests:

{
  "error": "Rate limit exceeded",
  "retry_after": 30
}

Implementation tips:

• Check X-RateLimit-Remaining before making requests
• Implement exponential backoff on 429 responses
• Batch operations where possible
• Contact support for higher limits if needed

Error Handling

Understanding API error responses and how to troubleshoot issues.

HTTP Status Codes

Error Response Format

{
  "message": "Validation failed",
  "errors": {
    "domain_name": ["Domain name is required"],
    "automation_level": ["Invalid automation level"]
  }
}

Common Error Scenarios