Webhook events

Each webhook delivery carries a data array of event objects. This page lists every event type and its fields. Setting up a subscription, verifying deliveries and responding to them are on Webhooks.

Every event object contains an event_type field plus the fields listed below. Fields marked optional may be absent entirely; do not assume a null.

📘

Reading the samples

Values appear as <field_name> placeholders rather than invented example data, so that each one names the value that belongs there. Substitute your own. Types, formats, and whether a field is required are in the table under each sample; where a field has a fixed set of possible values, they are listed there too.

Quoting follows the real payload: a placeholder in quotes is a string, and one without quotes is not.

RTTM_TIN_VALIDATION

The result of a real-time TIN matching request.

{
  "event_type": "RTTM_TIN_VALIDATION",
  "validation_id": "<validation-request-id>",
  "status": "<tin_verification_status>",
  "validation_date": "<validation_date>"
}

ACCOUNT_OWNER_TIN_VALIDATION

A TIN matching result for an account owner. Send recipient tax data shows how recipient TINs reach Taxbit.

{
  "event_type": "ACCOUNT_OWNER_TIN_VALIDATION",
  "account_owner_id": "<account_owner_id>",
  "account_owner_external_id": "<account_owner_external_id>",
  "status": "<tin_verification_status>",
  "validation_date": "<validation_date>"
}

TAX_DOCUMENTATION_TIN_VALIDATION

A TIN matching result tied to a specific tax documentation submission. Send recipient tax data shows how those submissions reach Taxbit.

{
  "event_type": "TAX_DOCUMENTATION_TIN_VALIDATION",
  "tax_documentation_id": "<tax_documentation_id>",
  "account_owner_id": "<account_owner_id>",
  "account_owner_external_id": "<account_owner_external_id>",
  "status": "<tin_verification_status>",
  "validation_date": "<validation_date>"
}

ACCOUNT_OWNER_TAX_DOCUMENTATION_STATUS

The current tax documentation state for an account owner. Sent whenever any of it changes. For what the statuses mean, see Send recipient tax data, Collect seller data, and Collect self-certifications.

The event carries up to three sub-objects, one per kind of submission on file. Each is present only if a submission of that kind exists, so check for the key before reading it. An account owner may have any combination.

{
  "event_type": "ACCOUNT_OWNER_TAX_DOCUMENTATION_STATUS",
  "account_owner_id": "<account_owner_id>",

  "w_form_questionnaire": {
    "data_collection_status": "<data_collection_status>",
    "type": "<document_type>",
    "needs_resubmission": false,
    "tax_documentation_status": "<tax_documentation_status>",
    "tin_status": "<tin_verification_status>",
    "tin_validation_date": "<tin_validation_date>",
    "expiration_date": "<expiration_date>",
    "treaty_claim_status": "<treaty_claim_status>",
    "issues": []
  },

  "dps_questionnaire": {
    "data_collection_status": "<data_collection_status>",
    "expiration_date": "<expiration_date>",
    "vat_status": "<vat_status>",
    "vat_validation_date": "<vat_validation_date>"
  },

  "self_certification": {
    "data_collection_status": "<data_collection_status>",
    "needs_resubmission": true,
    "tax_documentation_status": "<tax_documentation_status>",
    "issues": [
      {
        "issue_type": "<issue_type>",
        "created_at": "<created_at>",
        "details": [
          {
            "field": "<field_name>",
            "description": "<validation_error_description>"
          }
        ]
      }
    ]
  }
}

w_form_questionnaire: data_collection_status, type (the document type), needs_resubmission (boolean), tax_documentation_status, and issues. W-9 submissions additionally carry tin_status and tin_validation_date; W-8 submissions additionally carry expiration_date and treaty_claim_status.

dps_questionnaire: data_collection_status, expiration_date, vat_status, and vat_validation_date.

self_certification: data_collection_status, needs_resubmission (boolean), tax_documentation_status, and issues.

issues is an array, empty when there is nothing wrong. Each entry has an issue_type, a created_at timestamp, and a details array of { field, description } objects naming the specific problems.

FORM_STATUS_UPDATE

A tax form has been generated, filed, or deleted.

{
  "event_type": "FORM_STATUS_UPDATE",
  "organization_id": "<organization_id>",
  "account_id": "<account_id>",
  "alternate_account_id": "<alternate_account_id>",
  "form_type": "<form_type>",
  "tax_year": <tax_year>,
  "status": "<form_status>"
}

form_type is one of: 1099_DA, 1099_B, 1099_DIV, 1099_INT, 1099_K, 1099_MISC, 1099_NEC, 1099_R, 1042_S, 5498, DAC7, RMD_STATEMENT, GAIN_LOSS_SUMMARY, GAIN_LOSS_SUMMARY_PDF, TRANSACTION_SUMMARY, TRANSACTION_SUMMARY_PDF.

status means:

• Generated: the form has been created and can be retrieved via the tax documents endpoint, GET /v1/accounts/{id}/tax-documents.
• Filed: the form has been filed with the tax authority. The form's contents are unchanged from Generated.
• Deleted: a previously generated form has been deleted and is no longer retrievable. A form that has been filed cannot be deleted.

Retrieve US tax forms shows how to list and download forms from that endpoint.

INVENTORY_UPDATE

An account's transaction inventory has changed, and downstream figures may need recalculating. For how it fits with reading inventory and gains, see Know when inventory and gains are current and Send transactions and read gains.

{
  "id": "<event_id>",
  "event_type": "INVENTORY_UPDATE",
  "account_id": "<account_id>",
  "latest_transaction_datetime": "<latest_transaction_datetime>",
  "update_from_datetime": "<update_from_datetime>",
  "latest_transaction_id": "<transaction_id>",
  "update_from_transaction_id": "<transaction_id>"
}

🚧

Handle the deletion case

When transactions are deleted, both *_transaction_id fields are absent. Fall back to the datetime range: code that assumes the transaction IDs are always present will throw on exactly the events that matter most.

Where to go next

• Webhooks: set up a subscription, verify the signature, and respond to each delivery.
• Delivery guarantees: retries, duplicates, and ordering.