Webhooks

Register a webhook URL to receive real-time notifications instead of polling. Subscribe to specific event types for granular control.

Event types

Event Type	Trigger
research.completed	Research job finished successfully
research.failed	Research job failed
bulk.completed	Bulk job finished
bulk.failed	Bulk job failed
list.analyzed	List analysis finished
list.failed	List analysis failed
watchlist.change_detected	Significant score change on watched company

Event envelope

Every webhook delivery uses a structured event envelope:

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "research.completed",
  "created_at": "2026-02-16T12:00:00Z",
  "data": {
    "job_id": 123,
    "document_id": 456,
    "company_url": "https://example.com"
  }
}

POST /v1/webhooks/register

Register or update your webhook URL. Optionally subscribe to specific event types (null = all events). Returns a secret for HMAC signature verification.

Request body

{
  "url": "https://yourserver.com/webhook",
  "event_types": ["research.completed", "bulk.completed"]
}

wh = client.register_webhook(
    url="https://yourserver.com/webhook",
    event_types=["research.completed", "bulk.completed"]
)
print(wh["secret"])  # Store this securely!

curl -X POST https://auggie.tools/v1/webhooks/register \
  -H "Authorization: Bearer aug_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourserver.com/webhook", "event_types": ["research.completed"]}'

Response

{
  "object": "webhook",
  "url": "https://yourserver.com/webhook",
  "secret": "a1b2c3...hex...",
  "active": true,
  "event_types": ["research.completed", "bulk.completed"]
}

GET /v1/webhooks

Get your current webhook configuration.

Response

{
  "object": "webhook",
  "url": "https://yourserver.com/webhook",
  "active": true,
  "event_types": ["research.completed", "bulk.completed"]
}

DELETE /v1/webhooks

Remove your webhook. Returns 204 on success.

Verifying signatures

Each webhook delivery includes an X-Auggie-Signature header. Verify it using the secret from registration:

from auggie import Webhook, WebhookSignatureError

try:
    event = Webhook.construct_event(
        payload=request.body,
        signature_header=request.headers["X-Auggie-Signature"],
        secret="your_webhook_secret"
    )
    print(f"Event {event['type']}: {event['data']}")
except WebhookSignatureError:
    return Response(status_code=400)

import hashlib, hmac, json

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    body = json.dumps(
        json.loads(payload),
        separators=(",", ":"),
        sort_keys=True
    ).encode()
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)