Webhooks Guide
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:
- Contact Implementations: Contact your TaxBit Implementation Manager to create, update or delete a webhook subscription.
- Provide Endpoint: Supply the URL of your webhook endpoint.
- 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.
- 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:
- Maximum RPS
- Maximum retry attempts
- Maximum time to attempt a retry
- 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 whent the latest transaction has been 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 25 days ago