Webhooks — Quick Start - SANNOS Partner API

Instead of polling for document status, register a webhook URL and SANNOS will push notifications to you the moment a document finishes processing.

1. Register your endpoint

Your URL must be HTTPS and respond within 10 seconds.

curl -X PUT "https://sandbox-api.sannos.ai/v2/webhooks" \
  -H "X-API-Key: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/eve",
    "eventTypes": ["document.processing.completed", "document.processing.failed"]
  }'

The response includes a secret field — copy it immediately and store it securely. It is shown only once and cannot be retrieved later.

2. Receive events

SANNOS sends a POST request to your URL with this structure:

{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
  "event": "document.processing.completed",
  "timestamp": "2025-01-20T14:30:00Z",
  "data": {
    "documentId": "01DOC...",
    "companyId": "01CMP...",
    "fileName": "policy.pdf",
    "status": "Processed",
    "processedAt": "2025-01-20T14:30:00Z"
  }
}

3. Verify the signature

Every delivery includes an X-EVE-Signature header. Verify it before processing:

signing_payload = X-EVE-Timestamp + "." + raw_request_body
expected        = "sha256=" + HMAC-SHA256(your_secret, signing_payload).hex()

Always use a timing-safe comparison — never plain string equality. Python:

import hmac, hashlib

def verify(secret, timestamp, body, signature):
    payload = f"{timestamp}.{body}"
    expected = "sha256=" + hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

JavaScript / Node.js:

const crypto = require("crypto");

function verify(secret, timestamp, body, signature) {
  const payload = `${timestamp}.${body}`;
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(payload).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

C# / .NET:

using System.Security.Cryptography;
using System.Text;

bool Verify(string secret, string timestamp, string body, string signature) {
    var payload  = $"{timestamp}.{body}";
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash     = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var expected = Encoding.UTF8.GetBytes("sha256=" + Convert.ToHexString(hash).ToLowerInvariant());
    return CryptographicOperations.FixedTimeEquals(expected, Encoding.UTF8.GetBytes(signature));
}

4. Respond with 2xx

Return any 2xx status code to acknowledge receipt. SANNOS retries up to 5 times on failure, with increasing delays (1s → 5s → 30s → 2min). After 10 consecutive failures, the webhook is automatically deactivated — call PUT /v2/webhooks to re-activate.

Introduction

Guides

Reference

Webhooks — Quick Start

1. Register your endpoint

2. Receive events

3. Verify the signature

4. Respond with 2xx

​1. Register your endpoint

​2. Receive events

​3. Verify the signature

​4. Respond with 2xx

1. Register your endpoint

2. Receive events

3. Verify the signature

4. Respond with 2xx