TaxuDOCS
DashboardSign in

Webhooks

Receive real-time notifications when events occur in your Taxu account. Build reactive integrations with instant event delivery.

How Webhooks Work

Webhooks allow you to receive HTTP POST notifications when specific events happen in your Taxu account. Instead of polling the API, Taxu will push data to your server in real-time.

1

Configure Endpoint

Set up a URL on your server to receive webhook events

2

Subscribe to Events

Choose which events you want to be notified about

3

Receive Notifications

Get real-time POST requests when events occur

Trigger Webhook Events with Taxu CLI

Test your webhook integrations without waiting for real events. The Taxu CLI lets you trigger any webhook event instantly in sandbox mode.

List All Available Events

See all webhook events supported by the Taxu CLI:

taxu trigger --help

Trigger a Specific Event

Trigger any event by replacing <EVENT> with the event name:

taxu trigger <EVENT>

For example, trigger a tax filing submission event:

taxu trigger tax.filing.submitted

Customize Event Data

Override default parameters using the --override flag:

# Set a top-level parametertaxu trigger payment.succeeded --override payment:amount=5000# Set nested parameterstaxu trigger tax.filing.accepted --override filing:"taxpayer[ssn]"=123-45-6789# Multiple overridestaxu trigger document.processed \ --override document:type=w2 \ --override document:confidence=98

Note: The Taxu CLI automatically generates related events when needed. For example, triggering tax.filing.submitted may also generate tax.filing.created first.

Available Events

Tax Filing Events

tax.filing.created

Triggered when a new tax filing is created

tax.filing.submitted

Triggered when a tax return is submitted to the IRS

tax.filing.accepted

Triggered when the IRS accepts a tax return

tax.filing.rejected

Triggered when the IRS rejects a tax return

tax.filing.amended

Triggered when an amended return is filed

Payment Events

payment.succeeded

Triggered when a payment is successfully processed

payment.failed

Triggered when a payment fails

payment.refunded

Triggered when a payment is refunded

Banking Events

transaction.posted

Triggered when a bank transaction is posted

account.updated

Triggered when account information changes

transfer.completed

Triggered when a transfer completes

Document Events

document.uploaded

Triggered when a document is uploaded

document.processed

Triggered when document processing completes

document.verified

Triggered when a document is verified

Webhook Payload Example

All webhook events follow this structure:

{
  "id": "evt_1234567890",
  "object": "event",
  "type": "tax.filing.submitted",
  "created": 1704067200,
  "data": {
    "object": {
      "id": "filing_1234567890",
      "object": "tax_filing",
      "status": "submitted",
      "tax_year": 2024,
      "filing_type": "1040",
      "submission_id": "sub_abc123xyz",
      "taxpayer": {
        "name": "John Doe",
        "ssn": "***-**-6789"}
    }
  }
}

Verifying Webhook Signatures

Taxu signs all webhook requests with HMAC-SHA256. Always verify the signature to ensure the request came from Taxu:

Node.js Example

<span className="text-purple-400">const</span> <span className="text-blue-400">crypto</span> = <span className="text-pink-400">require</span>(<span className="text-yellow-300">'crypto'</span>);

<span className="text-purple-400">function</span> <span className="text-emerald-400">verifyWebhookSignature</span>(<span className="text-orange-400">payload</span>, <span className="text-orange-400">signature</span>, <span className="text-orange-400">secret</span>) {
  <span className="text-purple-400">const</span> <span className="text-blue-400">hmac</span> = crypto.<span className="text-emerald-400">createHmac</span>(<span className="text-yellow-300">'sha256'</span>, secret);
  <span className="text-purple-400">const</span> <span className="text-blue-400">digest</span> = hmac.<span className="text-emerald-400">update</span>(payload).<span className="text-emerald-400">digest</span>(<span className="text-yellow-300">'hex'</span>);
  <span className="text-purple-400">return</span> crypto.<span className="text-emerald-400">timingSafeEqual</span>(
    Buffer.<span className="text-emerald-400">from</span>(signature),
    Buffer.<span className="text-emerald-400">from</span>(digest)
  );
}

<span className="text-slate-500">// In your webhook handler</span>
app.<span className="text-emerald-400">post</span>(<span className="text-yellow-300">'/webhooks/taxu'</span>, (<span className="text-orange-400">req</span>, <span className="text-orange-400">res</span>) => {
  <span className="text-purple-400">const</span> <span className="text-blue-400">signature</span> = req.headers[<span className="text-yellow-300">'x-taxu-signature'</span>];
  <span className="text-purple-400">const</span> <span className="text-blue-400">payload</span> = JSON.<span className="text-emerald-400">stringify</span>(req.body);
  
  <span className="text-purple-400">if</span> (!<span className="text-emerald-400">verifyWebhookSignature</span>(payload, signature, process.env.WEBHOOK_SECRET)) {
    <span className="text-purple-400">return</span> res.<span className="text-emerald-400">status</span>(<span className="text-purple-400">401</span>).<span className="text-emerald-400">send</span>(<span className="text-yellow-300">'Invalid signature'</span>);
  }
  
  <span className="text-slate-500">// Process the webhook</span>
  <span className="text-purple-400">const</span> <span className="text-blue-400">event</span> = req.body;
  console.<span className="text-emerald-400">log</span>(<span className="text-yellow-300">'Received event:'</span>, event.type);
  
  res.<span className="text-emerald-400">status</span>(<span className="text-purple-400">200</span>).<span className="text-emerald-400">send</span>(<span className="text-yellow-300">'OK'</span>);
});

Important: The webhook secret is provided when you create a webhook endpoint in the developer portal. Store it securely as an environment variable.

Best Practices

⚡

Return 200 Quickly

Respond with HTTP 200 within 5 seconds. Process the event asynchronously if needed to avoid timeouts.

🔄

Handle Duplicates

Use the event ID to ensure idempotency. The same event may be sent multiple times due to retries.

🔒

Verify Signatures

Always verify the HMAC signature to ensure requests are authentically from Taxu and prevent spoofing.

🛡️

Use HTTPS

Webhook endpoints must use HTTPS in production for secure transmission of sensitive data.

📝

Log Everything

Keep detailed logs of all webhook deliveries, responses, and errors for debugging and audit trails.

Ready to Get Started?

Configure webhook endpoints and view delivery logs in the developer portal.