Webhooks

Receive real-time notifications when events occur in your CRM.

Overview

Webhooks send HTTP POST requests to your endpoint when events happen:

• Client created or updated
• Invoice created, sent, or paid
• Quote accepted or rejected
• And more...

Creating a Webhook

1. Go to Settings → Integrations → Webhooks
2. Click Create Webhook
3. Configure:
   • URL: Your endpoint URL (must be HTTPS)
   • Event Types: Select events to subscribe to
   • Status: Active or Inactive
4. Click Save
5. Copy the Signing Secret (shown only once)

Available Events

Client Events

• client.created - New client created
• client.updated - Client information updated

Invoice Events

• invoice.created - New invoice created
• invoice.updated - Invoice updated
• invoice.sent - Invoice sent to client
• invoice.paid - Invoice marked as paid
• invoice.status_updated - Invoice status changed

Quote Events

• quote.created - New quote created
• quote.sent - Quote sent to client
• quote.accepted - Quote accepted by client
• quote.rejected - Quote rejected by client

Webhook Payload

Structure

{
  "event": "client.created",
  "timestamp": "2024-12-13T10:00:00Z",
  "data": {
    "id": "uuid",
    "company_name": "Example Corp",
    "email": "contact@example.com"
  }
}

Event Field

The event field indicates the event type:

• Matches the event type you subscribed to
• Use to route to appropriate handlers

Data Field

The data field contains the resource:

• Full resource object
• Same structure as API responses
• Includes all fields

Signature Verification

Why Verify?

Always verify webhook signatures to ensure:

• Requests come from autoch.at CRM
• Data hasn't been tampered with
• Security and integrity

HMAC Signature

Webhooks include an HMAC-SHA256 signature:

X-Webhook-Signature: sha256=signature_here

Verification Process

1. Get the signing secret from webhook settings
2. Create signature from request body
3. Compare with X-Webhook-Signature header
4. Reject if signatures don't match

Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(body)).digest('hex');
  const expectedSignature = `sha256=${digest}`;
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Example (Python)

import hmac
import hashlib
import json

def verify_webhook(body, signature, secret):
    digest = hmac.new(
        secret.encode('utf-8'),
        json.dumps(body).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    expected_signature = f'sha256={digest}'
    
    return hmac.compare_digest(signature, expected_signature)

Retry Logic

Automatic Retries

Webhook delivery includes automatic retries:

• Exponential backoff: 1m, 5m, 30m, 2h, 12h
• Maximum 5 attempts
• Failed after max attempts

Response Requirements

Your endpoint should:

• Return 200 OK for successful processing
• Return 4xx for client errors (no retry)
• Return 5xx for server errors (will retry)
• Process within 30 seconds

Retry Headers

X-Webhook-Attempt: 1
X-Webhook-Retry-After: 60

Testing Webhooks

Test Button

1. Open webhook in settings
2. Click Test Webhook
3. System sends test event
4. Check your endpoint logs

Test Payload

Test events use this structure:

{
  "event": "webhook.test",
  "timestamp": "2024-12-13T10:00:00Z",
  "data": {
    "message": "Test webhook"
  }
}

Webhook Logs

Viewing Logs

1. Open webhook in settings
2. Click View Logs
3. See delivery history:
   • Timestamp
   • Event type
   • Status (delivered, failed, pending)
   • Response code
   • Error messages

Log Details

Each log entry shows:

• Request sent
• Response received
• Retry attempts
• Error details

Best Practices

Endpoint Requirements

• Use HTTPS: Required for security
• Return quickly: Process asynchronously if needed
• Handle errors: Return appropriate status codes
• Log everything: Track all webhook deliveries
• Idempotent processing: Handle duplicate events

Security

• Verify signatures: Always verify HMAC signatures
• Use HTTPS: Never use HTTP
• Validate data: Check data before processing
• Rate limiting: Implement rate limiting on your endpoint
• Monitor logs: Watch for suspicious activity

Error Handling

• Return 200 quickly: Acknowledge receipt
• Process asynchronously: Don't block on processing
• Retry logic: Implement your own retry if needed
• Dead letter queue: Store failed events for review

Webhook Status

Active

• Webhooks are delivered
• Events are sent
• Monitor logs regularly

Inactive

• Webhooks are paused
• No events sent
• Can be reactivated

Next Steps

• API Documentation - Learn about the API
• Connectors - Set up connectors
• WordPress Plugin - Integrate with WooCommerce