Guides

Webhooks Guide

Suggest Edits

Webhooks allow you to receive real-time updates about specific events from Taxbit directly to your server. They are commonly used to automate workflows, trigger business processes, or keep data in sync between systems. By subscribing to specific events, you can receive notifications whenever those events occur.

Getting Started

To enable webhook events, you need to register a webhook subscription for your organization. Once you’re subscribed, Taxbit will push data to your subscription endpoint for the events to which you’re subscribed.

To begin using Taxbit webhooks:

  1. Contact Implementations: Contact your TaxBit Implementation Manager to create, update or delete a webhook subscription.
  2. Provide Endpoint: Supply the URL of your webhook endpoint.
  3. Select Events: Specify the event types you wish to subscribe to (see below for the list of currently-supported events). Taxbit currently supports webhook alerts for Tax Identification Number (TIN) match results and changes to W8 and W9 form statuses.
  4. Configure delivery (optional): By default Taxbit will deliver events at a maximum rate of 300 requests-per-second (RPS). If a request fails, Taxbit will make two retry attempts over the next hour. You can substitute your own values for:
    1. Maximum RPS
    2. Maximum retry attempts
    3. Maximum time to attempt a retry
  5. Authenticate Subscription: Your Implementations Manager will confirm the subscription and provide you with a secret key for authenticating webhook requests for both.

📘

Taxbit uses HTTPS to send webhook events as a JSON payload.

Webhook Events

By registering a webhook endpoint for your organization that includes the event types that you’d like Taxbit to deliver, you enable Taxbit to automatically send webhook payloads as POST requests to the registered endpoint for your application.

You can configure the subscription to cap the number of maximum events contained in each POST request, as well as a retry policy and rate limit. An example request is included below.

POST https://customer.site/webhook-endpoint
x-taxbit-signature:    v1=<sha256-hmac-signature>
x-taxbit-source:	   webhook
x-trace-id:	          1a0f28b1-092d-4001-8ca1-17d91037610b
content-type:          application/json
{
  "timestamp": "2024-03-01T12:00:00.000Z",
  "data": [
    {
      "event_type":  "<event-type>",
      "<field_a>":   "<value-a>",
      "<field_b>":   "<value-b>",
    }
  ]
}

TaxBit currently supports the following event types, and we’re continually adding more. Each event contains an event_type, plus additional metadata that add context to each event (such as account_id) that can be used in subsequent GET requests.

Real-Time TIN Validation

RTTM_TIN_VALIDATION

{
	"event_type": "RTTM_TIN_VALIDATION",
	"validation_id": "<validation-request-id>",
	"status": "<tin_verification_status>",
	"validation_date": "2024-07-09T02:56:07.000Z"
}

Tax Documentation TIN Validation

TAX_DOCUMENTATION_TIN_VALIDATION

{
	"event_type": "TAX_DOCUMENTATION_TIN_VALIDATION",
	"tax_documentation_id": "<tax_documentation_id>",
	"account_owner_id": "<account_owner_id>",
	"status": "<tin_verification_status>",
	"validation_date": "2024-07-09T02:56:07.000Z"
}

Account Owner TIN Validation

ACCOUNT_OWNER_TIN_VALIDATION

{
	"event_type": "ACCOUNT_OWNER_TIN_VALIDATION",
	"account_owner_id": "<account_owner_id>",
	"status": "<tin_verification_status>",
	"validation_date": "2024-07-09T02:56:07.000Z"
}

Inventory Update

INVENTORY_UPDATE

{
    "id": "<event_id>",
    "event_type": "INVENTORY_UPDATE",
    "latest_transaction_datetime": "2020-11-25T12:53:14.000Z",
    "account_id": "<account_id>",
    "latest_transaction_id": "<transaction_id>" //optional; ommitted when the latest transaction has been deleted
}

Tax Form Status Update

FORM_STATUS_UPDATE

{
        "event_type": "FORM_STATUS_UPDATE",
        "organization_id" : "<organization_id>",
        "account_id": "<account_id>",
        "alternate_account_id": "<alternate_account_id>", //optional; ommitted when this field does not exist
        "form_type": "<form_type>",//returns one of - GAIN_LOSS_SUMMARY GAIN_LOSS_SUMMARY_PDF 1099_B 1099_DIV 1099_INT 1099_K 1099_MISC 1099_NEC 1099_R 5498 RMD_STATEMENT 1042_S DAC7 TRANSACTION_SUMMARY TRANSACTION_SUMMARY_PDF
        "tax_year": "<tax_year>", 
        "status": "<form_status>" //returns one of - Generated, Filed, Deleted
}
  • status indicates the form's status and can be the following:
    • Generated indicates that the tax form has been created and can be viewed, or accessed through this API endpoint
    • Filed indicates that the tax form has been filed with authority. The tax form itself has not changed from the Generated state.
    • Deleted indicates that a Generated form has been deleted and is no longer viewable or accessible. A Filed form cannot be deleted.

Security

Taxbit uses a Hash-based Message Authentication Code (HMAC) method to authenticate webhook deliveries. Each POST request includes an x-taxbit-signature header that can be used to authenticate the request. You’ll get a secret key when creating your webhook subscription, and TaxBit will sign each payload using that key and the HMAC-SHA256 hashing algorithm.

Your application code can then follow the same steps – sign and encode the request payload with your secret key – and validate that the resulting signature is included in the header. (The header itself is a comma-separated list of signature values, each prefixed with a version, to support seamless secret rotation.)

const crypto = require('crypto')
const signatureHeader = 'x-taxbit-signature'
const signatureVersion = 'v1'
const signatureAlgorithm = 'sha256'
const encodeFormat = 'base64'
const hmacSecret = process.env.WEBHOOK_SECRET

app.post('/webhook_endpoint', (req, res) => {
  // Create digest with payload + hmac secret
  const payload = req.rawBody
  const hmac = crypto.createHmac(signatureAlgorithm, hmacSecret)

  hmac.update(payload);

  const digest = hmac.digest(encodeFormat)
  
  // Get signatures sent by TaxBit
  const signatures = req.get(signatureHeader) || ''

  // Validate that digest signature is included among TaxBit signatures
  if (signatures.split(',').includes(`${signatureVersion}=${digest}`)) {
    // Webhook Authenticated 
    // process and respond...
    res.json({ message: "Success" })
  } else{
    res.status(401).send('Unauthorized')
  }
})

Testing

Prior to enabling webhook deliveries for your production application, Taxbit supports test subscriptions that can be used to test and debug any issues. Each POST delivery contains an x-trace-id header to help aid debugging if necessary.

Updated 14 days ago