Custom Webhooks

What Are Webhooks?

Webhooks are HTTP callbacks that TuskCPA sends to your specified URL when certain events occur. Think of them as "reverse APIs" - instead of you polling our API for updates, we push updates to you in real-time.

Common Use Cases

Available Events

Subscribe to any of these events:

Setup Guide

Step 1: Create Webhook Endpoint

Build an HTTPS endpoint that can receive POST requests. This can be:

• • Cloud function (AWS Lambda, Google Cloud Functions, Azure Functions)
• • API route in your web application
• • Zapier or Make.com webhook receiver
• • Custom server endpoint

Step 2: Register Webhook in TuskCPA

Go to Settings → Integrations → Webhooks. Click "Add Webhook" and provide your endpoint URL and select which events to subscribe to.

Step 3: Handle Webhook Payload

Your endpoint will receive JSON payloads like this:

{
  "event": "document.uploaded",
  "timestamp": "2025-10-26T14:30:00Z",
  "data": {
    "client_id": "cli_abc123",
    "client_name": "Acme Corp",
    "document_id": "doc_xyz789",
    "document_name": "2024_W2.pdf",
    "document_type": "W-2",
    "uploaded_by": "client"
  }
}

Step 4: Verify Webhook Signature

Each webhook includes an X-TuskCPA-Signature header for security. Verify this signature to ensure requests are from TuskCPA and not forged.

Example: Slack Integration

// Node.js example
async function handleWebhook(req, res) {
  const event = req.body;
  
  if (event.event === 'document.uploaded') {
    await slack.chat.postMessage({
      channel: '#tax-team',
      text: `📄 ${event.data.client_name} uploaded ${event.data.document_name}`
    });
  }
  
  res.status(200).send('OK');
}

Best Practices

• Respond Quickly: Return 200 OK within 5 seconds. Do heavy processing asynchronously.
• Handle Retries: We retry failed webhooks up to 3 times. Make your endpoint idempotent.
• Verify Signatures: Always validate the webhook signature for security.
• Log Everything: Keep logs of received webhooks for debugging.
• Use HTTPS: Webhooks must be sent to HTTPS endpoints (no HTTP).

Testing Webhooks

Use the "Test Webhook" button in settings to send a sample payload to your endpoint. Verify your code handles it correctly before enabling in production.

Rate Limits

Webhooks have no rate limits. However, if your endpoint consistently fails or times out, we may temporarily disable the webhook to prevent overload.

Security

• Signature Verification: Use HMAC-SHA256 signature to verify authenticity
• HTTPS Only: All webhooks sent over encrypted connections
• IP Allowlisting: Optionally restrict to TuskCPA IP addresses
• Secrets Rotation: Rotate webhook secrets regularly