Skip to content

Webhooks

Webhooks notify your system when something happens, so you do not need to poll.

Event When
batch.completed All items in a batch were processed.
batch.failed A batch could not be processed, for example because of an unreadable file.
list.updated A source published a new version and it was indexed. Includes counts of added, changed and removed entries.
Terminal window
curl https://api.auto-compliance.com/v1/webhook-endpoints \
-H "Authorization: Bearer $AUTOCOMPLIANCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hooks/autocompliance", "events": ["batch.completed", "batch.failed"] }'

The response includes a secret (whsec_...). It is shown only once.

Every delivery has an AutoCompliance-Signature header:

AutoCompliance-Signature: t=1763640000,v1=3b1f0e1c...

v1 is the hex HMAC-SHA256 of "{t}.{raw request body}" using your endpoint secret. Always:

  1. Compute the HMAC over the raw body, before JSON parsing.
  2. Compare with a constant-time function.
  3. Reject events where t is more than 5 minutes old.
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
timestamp, signature = parts["t"], parts["v1"]
if abs(time.time() - int(timestamp)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
import crypto from 'node:crypto';
export function verify(rawBody, header, secret, tolerance = 300) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest('hex');
return expected.length === parts.v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
  • Respond with any 2xx status within 10 seconds. Do slow work asynchronously.
  • Failed deliveries are retried with exponential backoff for up to 24 hours.
  • Events can arrive more than once or out of order. Deduplicate on the event id.
  • Delivery logs and manual redelivery will be available in the merchant portal.