Skip to main content
Docs/Buyer/Webhooks

Webhooks

Webhooks push signal events to your server in real time, so you don't have to poll. This guide shows how to register a URL and verify the HMAC signature on every payload.

What you'll learn

  • How to register an endpoint
  • What event types you can subscribe to
  • How to verify the HMAC signature
  • How retries work

Step 1: Register a URL

  1. Open Settings → Webhooks.
  2. Click New endpoint.
  3. Paste your HTTPS URL (we don't accept HTTP).
  4. Pick the events you want to receive.
  5. Copy the Signing secret — store it as SIE_WEBHOOK_SECRET in your env.

Event types

EventWhen it fires
signal.matchedA new signal matches your subscriptions
signal.revealedYou spent credits to unlock
sequence.repliedA target replied to your outreach
credits.lowYou crossed 80% of your bucket

Step 2: Verify HMAC

Every request includes X-SIE-Signature and X-SIE-Timestamp. Compute HMAC-SHA256 of {timestamp}.{rawBody} using your signing secret, then compare in constant time.

javascript
import crypto from 'node:crypto'

export function verify(req, secret) {
  const ts = req.headers['x-sie-timestamp']
  const sig = req.headers['x-sie-signature']
  const payload = ts + '.' + req.rawBody
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(sig, 'hex'),
    Buffer.from(expected, 'hex'),
  )
}
python
import hmac, hashlib

def verify(headers, raw_body, secret):
    ts = headers["X-SIE-Timestamp"]
    sig = headers["X-SIE-Signature"]
    expected = hmac.new(
        secret.encode(),
        f"{ts}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

Step 3: Reject stale

Drop any request whose timestamp is older than 5 minutes — that prevents replay attacks even if your signing secret leaks momentarily.

Retries

Return a 2xx within 5 seconds. We retry non-2xx with exponential backoff for 24 hours: 1 min, 5 min, 30 min, 2 hr, 6 hr, 12 hr. After that we mark the endpoint failing and email you.

What's next?