Webhooks API

Create and manage webhook subscriptions to receive real-time notifications when events occur in CronDB.

tip

Try this endpoint live in the API Playground.

Requires Starter plan or above

The free plan does not include webhook access.

Endpoints

Method	Endpoint	Description
GET	/v1/webhooks	List your webhooks
POST	/v1/webhooks	Create a webhook
PUT	/v1/webhooks/{id}	Update a webhook
DELETE	/v1/webhooks/{id}	Delete a webhook
GET	/v1/webhooks/deliveries	List all deliveries
GET	/v1/webhooks/{id}/deliveries	List deliveries for a webhook
POST	/v1/webhooks/{id}/deliveries/{delivery_id}/retry	Retry a failed delivery

Plan Limits

Plan	Max Webhooks
Free	0
Starter	2
Pro	10
Enterprise	50

---

Create Webhook

POST /v1/webhooks

Parameter	Type	Required	Description
url	string	Yes	HTTPS endpoint URL
events	string[]	Yes	Event types to subscribe to (max 20)

curl -X POST \
  -H "Authorization: Bearer cdb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/crondb",
    "events": [
      "alert.domain_matched",
      "watchlist.domain_changed",
      "sequence.email_replied"
    ]
  }' \
  "https://api.crondb.com/v1/webhooks"

import requests

response = requests.post(
    "https://api.crondb.com/v1/webhooks",
    headers={"Authorization": "Bearer cdb_your_api_key_here"},
    json={
        "url": "https://yourapp.com/webhooks/crondb",
        "events": ["alert.domain_matched", "sequence.email_replied"],
    },
)
webhook = response.json()
print(f"Webhook ID: {webhook['id']}, Secret: {webhook['secret']}")

Response (201)

{
  "id": 1,
  "url": "https://yourapp.com/webhooks/crondb",
  "events": ["alert.domain_matched", "sequence.email_replied"],
  "secret": "whsec_abc123...",
  "is_active": true,
  "created_at": "2026-03-22T10:00:00Z"
}

Save the Secret

The webhook secret is shown only once. Use it to verify webhook signatures.

---

Available Events

Event	Trigger
search.alert	Saved search finds new matches
keyword.match	Tracked keyword detected
audience.updated	Audience has new matching domains
domain.new_match	New domain matches your criteria
domain.enriched	Domain enrichment completed
intent.high_detected	High-intent domain detected
watchlist.change	Watched domain data changed
list.item_added	Domain added to a lead list
list.status_changed	List item funnel status changed
export.completed	Export job finished
sequence.replied	Sequence email received a reply
sequence.bounced	Sequence email bounced
sequence.opened	Sequence email was opened
sequence.clicked	Sequence email link clicked
sequence.completed	Contact finished all sequence steps
sequence.unsubscribed	Contact unsubscribed
*	Subscribe to all events

---

List Deliveries

GET /v1/webhooks/deliveries

View delivery history with success/failure stats.

Parameter	Type	Default	Description
webhook_id	integer	null	Filter by webhook
event_type	string	null	Filter by event
limit	integer	100	Max results (max 200)

Response

{
  "deliveries": [
    {
      "id": 42,
      "webhook_id": 1,
      "event_type": "alert.domain_matched",
      "url": "https://yourapp.com/webhooks/crondb",
      "status": "delivered",
      "status_code": 200,
      "attempt": 1,
      "created_at": "2026-03-20T14:30:00Z"
    }
  ],
  "summary": {
    "total_delivered": 156,
    "total_failed": 3,
    "success_rate": 98.1,
    "avg_response_ms": 245
  }
}

---

Retry Failed Delivery

POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

Re-attempt delivery for a failed webhook. CronDB uses exponential backoff for automatic retries, but you can manually trigger a retry.

curl -X POST \
  -H "Authorization: Bearer cdb_your_api_key_here" \
  "https://api.crondb.com/v1/webhooks/1/deliveries/42/retry"

Webhook Payload Format

All webhook payloads follow this structure:

{
  "event": "alert.domain_matched",
  "timestamp": "2026-03-20T14:30:00Z",
  "webhook_id": 1,
  "data": { ... }
}

Headers included with each delivery:

Header	Description
Content-Type	application/json
X-CronDB-Event	Event type
X-CronDB-Signature	HMAC-SHA256 signature
X-CronDB-Delivery-ID	Unique delivery ID

Verifying Signatures

Verify webhook authenticity using the HMAC-SHA256 signature:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

const crypto = require("crypto");

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

Next Steps

• Webhook Events — Detailed payload schemas for each event
• Alerts — Set up alert rules
• Watchlist — Monitor domains for changes