Webhooks

Structurify can send webhook notifications when events occur, allowing you to build automated workflows without polling.

Supported Events

Event	Description
extraction.completed	Extraction job finished successfully
extraction.failed	Extraction job failed
export.ready	Large export file is ready for download

Webhook Payload

All webhooks include a JSON payload:

{
  "event": "extraction.completed",
  "timestamp": "2026-01-02T10:30:00Z",
  "data": {
    "job_id": "job_abc123",
    "project_id": "proj_xyz789",
    "status": "done",
    "total_tasks": 50,
    "completed_tasks": 48,
    "failed_tasks": 2
  },
  "signature": "sha256=..."
}

Verifying Signatures

Always verify webhook signatures to ensure requests are from Structurify.

Python

from structurify.webhooks import verify_signature

def handle_webhook(request):
    is_valid = verify_signature(
        payload=request.body,
        signature=request.headers['X-Structurify-Signature'],
        secret='your_webhook_secret'
    )

    if not is_valid:
        return {"error": "Invalid signature"}, 401

    event = json.loads(request.body)
    # Process event...

Node.js

import { verifyWebhookSignature } from '@structurify/sdk';

app.post('/webhook', (req, res) => {
  const isValid = verifyWebhookSignature({
    payload: req.body,
    signature: req.headers['x-structurify-signature'],
    secret: 'your_webhook_secret',
  });

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  // Process event...
});

Manual Verification

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)

Best Practices

1. Always verify signatures - Reject requests with invalid signatures
2. Respond quickly - Return 200 within 5 seconds, process async
3. Handle duplicates - Webhooks may be retried, use idempotency
4. Use HTTPS - Only use secure endpoints for webhooks
5. Log events - Keep audit logs of received webhooks

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook is marked as failed.