Webhooks

Receive real-time notifications on your server when something happens in AdFlow.

How it works

1. Register an HTTPS URL + secret at /webhook_endpoints/new
2. Select which events you want to receive
3. When the event occurs, AdFlow POSTs to your URL with a JSON payload
4. Your server validates the signature and processes the payload

Set up an endpoint

In /webhook_endpoints/new:

• URL: must be HTTPS and publicly accessible. No localhost support in production.
• Secret: random string (minimum 32 characters). Use openssl rand -hex 32 to generate.
• Events: select the types you want. Recommended start: campaign.* and webhook.failed.

After saving, click Send test event to confirm your URL is receiving.

Available events

Payload format

{
  "id": "evt_abc123",
  "event": "campaign.enqueued",
  "occurred_at": "2026-05-03T10:00:00Z",
  "organization_id": "org_xyz789",
  "data": {
    "resource_type": "campaign",
    "resource_id": "cmp_def456",
    "changes": {}
  }
}

Validate the HMAC signature

Every POST includes the X-AdFlow-Signature header: HMAC-SHA256 of the body using your secret. Always validate before processing.

# Ruby
secret   = ENV['ADFLOW_WEBHOOK_SECRET']
expected = OpenSSL::HMAC.hexdigest('SHA256', secret, request.raw_post)
received = request.headers['X-AdFlow-Signature']
halt 401 unless ActiveSupport::SecurityUtils.secure_compare(received, expected)

# Python
import hmac, hashlib, os
secret   = os.environ['ADFLOW_WEBHOOK_SECRET'].encode()
expected = hmac.new(secret, request.body, hashlib.sha256).hexdigest()
received = request.headers.get('X-AdFlow-Signature', '')
if not hmac.compare_digest(expected, received):
    abort(401)

Retry policy

If your server returns an error (4xx, 5xx) or doesn’t respond within 10s, AdFlow retries:

After 3 consecutive failures, logs webhook.failed in the audit log and stops retrying for that event.

Your endpoint should respond 200 OK even if you decide not to process the event — this prevents AdFlow from re-sending.