REST APIPlus Plan

Webhooks API

Receive real-time notifications when events occur in DDMARC. Configure webhook endpoints to integrate with your systems.

Event Types

Subscribe to one or more event types to receive notifications:

Event	Description
report.received	New DMARC aggregate report received
report.failure	Authentication failure detected in report
domain.verified	Domain ownership verified
domain.dns_changed	DNS record change detected
alert.triggered	Alert threshold exceeded

API Endpoints

Method	Endpoint	Description
GET	/api/v1/webhooks	List webhook endpoints
POST	/api/v1/webhooks	Create webhook endpoint
PUT	/api/v1/webhooks/:id	Update webhook
DELETE	/api/v1/webhooks/:id	Delete webhook
POST	/api/v1/webhooks/:id/test	Send test webhook

POST

Create Webhook Endpoint

Create a new webhook endpoint to receive event notifications.

POST /api/v1/webhooks

curl -X POST "https://api.ddmarc.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/ddmarc",
    "events": ["report.received", "report.failure"],
    "secret": "your-webhook-secret",
    "active": true
  }'

Request Body

Field	Type	Required	Description
url	string	Required	HTTPS URL to receive webhooks
events	array	Required	Event types to subscribe to
secret	string	Optional	Secret for signature verification
active	boolean	Optional	Enable/disable webhook (default: true)

Response201 Created

{
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhooks/ddmarc",
    "events": ["report.received", "report.failure"],
    "active": true,
    "created_at": "2024-01-20T15:00:00Z"
  }
}

POST

Send Test Webhook

Send a test payload to your webhook endpoint to verify it's working correctly.

POST /api/v1/webhooks/:id/test

curl -X POST "https://api.ddmarc.com/v1/webhooks/wh_abc123/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Payload Format

When an event occurs, DDMARC sends a POST request to your webhook URL with the following payload structure:

Example: report.received

{
  "id": "evt_xyz789",
  "type": "report.received",
  "created_at": "2024-01-20T15:30:00Z",
  "data": {
    "report_id": "rpt_abc123",
    "domain": "example.com",
    "reporter": "google.com",
    "total_count": 1250,
    "pass_rate": 98.4,
    "date_range": {
      "begin": "2024-01-19T00:00:00Z",
      "end": "2024-01-19T23:59:59Z"
    }
  }
}

Signature Verification

If you provide a secret when creating the webhook, DDMARC signs each request with an HMAC-SHA256 signature in the X-DDMARC-Signature header.

X-DDMARC-Signature: sha256=5d5b09...

Verification Example (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Retry Policy

Automatic Retries

Failed deliveries are retried up to 5 times with exponential backoff.

Timeout

Your endpoint must respond within 30 seconds or the request is considered failed.

Disabling

After consecutive failures, the webhook is automatically disabled.

Best Practices

Respond quickly

Return a 2xx status immediately, then process the payload asynchronously

Verify signatures

Always verify the X-DDMARC-Signature header to ensure authenticity

Handle duplicates

Use the event ID to deduplicate in case of retries

Use HTTPS

Webhook URLs must use HTTPS to ensure encrypted transmission

Webhook Object

Field	Type	Description
id	string	Unique webhook identifier
url	string	Endpoint URL
events	array	Subscribed event types
active	boolean	Whether webhook is enabled
created_at	string	ISO 8601 creation timestamp
last_triggered_at	string	Last successful delivery
failure_count	integer	Consecutive failures

Documentation