Skip to main content

Webhooks

Webhooks allow you to receive real-time HTTP callbacks when specific events occur in your AnotiAI account. This enables you to build integrations that react to changes in your account, such as usage thresholds, API key changes, or project updates.

Overview​

Webhooks are HTTP POST requests sent to a URL you specify (the endpoint) whenever a selected event occurs. All webhook payloads are signed using HMAC-SHA256 for security verification.

Key Features​

  • Real-time notifications: Get instant updates when events happen
  • Event filtering: Subscribe only to the events you care about
  • Secure delivery: All payloads are cryptographically signed
  • Retry mechanism: Automatic retries with configurable strategies
  • Event categories: Organized events by usage, API keys, and projects

Creating a Webhook​

  1. Navigate to the Webhooks page in your dashboard
  2. Click Create Webhook
  3. Configure the following:
    • Endpoint URL: The HTTPS URL where notifications will be sent
    • Events: Select which events you want to receive notifications for
    • Description (optional): A note to help you identify this webhook
note

Your endpoint must use HTTPS and be publicly accessible to receive webhook notifications.

Available Events​

Webhooks support events across multiple categories. You can subscribe to individual events or entire categories.

Usage Events​

EventDescription
usage.threshold_reachedUsage has reached a configured threshold

API Key Events​

EventDescription
key.createdA new API key has been created
key.revokedAn API key has been revoked
key.rotatedAn API key has been rotated

Project Events​

EventDescription
project.createdA new project has been created
project.updatedA project has been updated
project.deletedA project has been deleted

Webhook Payload​

Webhook payloads are sent as JSON via HTTP POST requests. Each payload includes:

{
  "event": "invoice.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  },
  "webhook_id": "wh_1234567890"
}

Common Payload Fields​

  • event: The event type (e.g., "invoice.created")
  • timestamp: ISO 8601 timestamp of when the event occurred
  • data: Event-specific payload data
  • webhook_id: Unique identifier for the webhook delivery
info

The exact structure of the data field varies by event type. Refer to the API reference for detailed payload schemas.

Security & Verification​

All webhook payloads are signed using HMAC-SHA256 to ensure they originate from AnotiAI and haven't been tampered with.

Verifying Signatures​

Each webhook request includes a X-AnotiAI-Signature header containing the signature. To verify:

  1. Get the raw request body
  2. Create an HMAC-SHA256 hash using your webhook's signing secret as the key
  3. Compare the computed signature with the one in the header
const crypto = require("crypto");

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex"),
  );
}
warning

Always verify webhook signatures before processing payloads to prevent security vulnerabilities.

Retry Mechanism​

If your endpoint doesn't respond successfully (HTTP 2xx status), AnotiAI will automatically retry delivery using an exponential backoff strategy.

Retry Configuration​

  • Maximum attempts: Up to 10 retries
  • Backoff strategy: Exponential (1s, 2s, 4s, 8s, etc.)
  • Timeout: 10 seconds per attempt

Response Requirements​

Your endpoint should respond with HTTP 2xx status codes to indicate successful processing. Other status codes will trigger retries.

Managing Webhooks​

Viewing Webhook Details​

  • Click on any webhook in the table to view detailed information
  • See delivery statistics, recent attempts, and configuration

Updating Webhooks​

Currently, webhooks cannot be modified after creation. To change configuration:

  1. Delete the existing webhook
  2. Create a new webhook with updated settings

Deleting Webhooks​

  1. Click the delete button next to the webhook you want to remove
  2. Confirm the deletion
caution

Deleted webhooks cannot be recovered. Make sure you no longer need the webhook before deleting.

Testing Webhooks​

You can test your webhook endpoints to ensure they're working correctly:

  1. Go to the webhook details panel
  2. Click Test Webhook
  3. AnotiAI will send a test payload to your endpoint

Best Practices​

Endpoint Design​

  • Use HTTPS: Always use secure connections
  • Respond quickly: Process webhooks asynchronously if needed
  • Handle duplicates: Implement idempotency to handle duplicate deliveries
  • Log deliveries: Keep records of received webhooks for debugging

Security​

  • Verify signatures: Always check the cryptographic signature
  • Validate payloads: Ensure the payload structure matches expectations
  • Use secrets securely: Store signing secrets securely, never in client-side code

Monitoring​

  • Monitor response times: Set up alerts for slow responses
  • Track success rates: Monitor webhook delivery success rates
  • Handle failures: Implement proper error handling and alerting

Troubleshooting​

Common Issues​

Webhook not receiving events

  • Check that the endpoint URL is correct and accessible
  • Verify the webhook is active
  • Ensure you've selected the correct events

Signature verification fails

  • Confirm you're using the correct signing secret
  • Check that you're using the raw request body for verification
  • Ensure proper encoding (UTF-8)

Timeout errors

  • Your endpoint must respond within 10 seconds
  • Consider processing webhooks asynchronously

Support​

If you're experiencing issues with webhooks, check the API Reference or contact support.

Last updated on