Webhooks API

Receive real-time notifications about TaxIntent status changes and fiscalization events. Webhooks ensure your application stays synchronized with TaxBridge processing.

Overview

Webhooks deliver asynchronous notifications to your application when TaxIntents change status or complete processing. This is essential for applications that need to react to fiscalization events without constant polling.

Event-Driven Architecture

Webhooks enable event-driven workflows where your application reacts to fiscalization completion, failures, or status changes in real-time.

Webhook Events

TaxBridge sends webhook notifications for key events in the TaxIntent lifecycle. Each event includes the full TaxIntent object and event-specific metadata.

tax_intent.succeeded

Fired when a TaxIntent is successfully fiscalized and FDN is obtained.

{
  "event": "tax_intent.succeeded",
  "data": {
    "id": "ti_xyz789",
    "status": "succeeded",
    "fdn": "1234567890",
    "verification_code": "ABC123XYZ",
    "qrcode": "base64_encoded_data"
  }
}

tax_intent.failed

Fired when a TaxIntent fails permanently after all retry attempts.

{
  "event": "tax_intent.failed",
  "data": {
    "id": "ti_xyz789",
    "status": "failed",
    "last_error": "Network timeout after 10 retries"
  }
}

tax_intent.processing

Fired when a TaxIntent begins processing (after confirmation).

{
  "event": "tax_intent.processing",
  "data": {
    "id": "ti_xyz789",
    "status": "processing"
  }
}

tax_intent.requires_correction

Fired when URA rejects with a correctable error (unit mismatch, etc.).

{
  "event": "tax_intent.requires_correction",
  "data": {
    "id": "ti_xyz789",
    "status": "requires_correction",
    "last_error": "Unit of measure mismatch"
  }
}

Webhook Delivery

Webhooks are delivered via HTTP POST to your configured endpoint. TaxBridge expects a 2xx response to confirm successful delivery.

# Webhook Delivery

POST https://your-app.com/webhooks/taxbridge

Content-Type: application/json

User-Agent: TaxBridge-Webhook/1.0

X-TaxBridge-Signature: sha256=abc123...

{
  "event": "tax_intent.succeeded",
  "data": { ... },
  "webhook_id": "wh_123456",
  "created_at": "2025-12-10T10:00:00Z"
}

Delivery Guarantees

Webhooks are delivered at least once. If your endpoint returns a non-2xx response, TaxBridge will retry with exponential backoff for up to 24 hours.

Security & Verification

Verify webhook authenticity using the X-TaxBridge-Signature header to ensure requests originate from TaxBridge.

# Verify webhook signature (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === `sha256=${expectedSignature}`
}

Webhook Secret

Your webhook secret is available in the TaxBridge dashboard. Keep it secure and rotate regularly.

Configuration

Configure webhook endpoints in your TaxBridge dashboard or via API. You can set up multiple endpoints for different environments.

# Configure webhook endpoint

curl -X POST https://api.taxbridge.com/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/taxbridge",
    "events": ["tax_intent.succeeded", "tax_intent.failed"],
    "active": true
  }'

Configuration Response

{
  "id": "we_abc123",
  "url": "https://your-app.com/webhooks/taxbridge",
  "events": ["tax_intent.succeeded", "tax_intent.failed"],
  "active": true,
  "secret": "whsec_..."
}

Retry Logic

TaxBridge implements intelligent retry logic for webhook delivery failures. Failed deliveries are retried with exponential backoff.

Attempt	Delay	Cumulative Time	HTTP Status
1	0s	0s	Any non-2xx
2	30s	30s	5xx, timeout
3	5m	5m 30s	5xx, timeout
4	30m	35m 30s	5xx, timeout
5+	2h	Up to 24h	5xx, timeout

Final Failure

After 24 hours of retries, failed webhooks are logged in your dashboard. You can manually retry or reconfigure the endpoint.

Testing Webhooks

Test your webhook endpoint with sample payloads before going live. Use the dashboard to send test events to your configured endpoints.

# Send test webhook

curl -X POST https://api.taxbridge.com/v1/webhook-endpoints/we_abc123/test \

-H "Authorization: Bearer sk_test_1234567890abcdef" \

-H "Content-Type: application/json" \

-d '

"event": "tax_intent.succeeded"

'

Test Delivery

Test webhooks are sent immediately and include sample data. Check your endpoint logs to verify proper handling.

Best Practices

1

Verify Signatures

Always verify the X-TaxBridge-Signature header to ensure webhook authenticity.

2

Handle Idempotency

Use the webhook_id field to handle duplicate deliveries gracefully.

3

Respond Quickly

Return a 2xx response within 10 seconds to avoid retry delays.

4

Log Everything

Log all webhook attempts, successes, and failures for debugging.

Implementation Status

Coming Soon

Webhooks are currently in development. The API endpoints and event structure are planned but not yet implemented. Check back for updates or contact support for early access.