Developers/Docs/Webhooks

Webhooks

Receive real-time notifications when signals match your criteria, enrichment completes, or auto-buy rules trigger. All webhook payloads are signed with HMAC-SHA256.

Setting Up Webhooks

POST/api/v1/webhooks

json

{
  "url": "https://your-app.com/webhook/sie",
  "events": ["signal.new", "enrichment.complete", "autobuy.triggered"],
  "secret": "your_webhook_secret"
}

json

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhook/sie",
  "events": ["signal.new", "enrichment.complete", "autobuy.triggered"],
  "status": "active",
  "created_at": "2026-03-27T12:00:00Z"
}

Event Types

Event	Description
signal.new	A new signal matches your subscribed filters
signal.upgraded	An existing signal changed intent level (e.g. warm to hot)
enrichment.complete	An async enrichment request has finished
autobuy.triggered	An auto-buy rule purchased a signal on your behalf
autobuy.budget_warning	Auto-buy budget is 80%+ consumed
contact.revealed	A batch reveal has completed

Webhook Payload

Every webhook delivery includes these headers:

Header	Description
X-SIE-Signature	HMAC-SHA256 hex digest of the request body
X-SIE-Timestamp	Unix timestamp of when the event was sent
X-SIE-Event	The event type (e.g. signal.new)

Signature Verification

Always verify the signature before processing a webhook. The signature is computed as HMAC-SHA256(timestamp + "." + body, secret).

python

import hmac
import hashlib
import time

def verify_webhook(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Reject if timestamp is older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

javascript

const crypto = require("crypto");

function verifyWebhook(body, signature, timestamp, secret) {
  // Reject if timestamp is older than 5 minutes
  if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");

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

Retry Policy

If your endpoint returns a non-2xx status code or times out (10s), we retry with exponential backoff:

Attempt 1: immediate
Attempt 2: after 30 seconds
Attempt 3: after 5 minutes
Attempt 4: after 30 minutes
Attempt 5: after 2 hours (final)

After 5 failed attempts, the webhook is marked as failing and you will receive an email notification.