Skip to main content
Version: 1.6.1

Webhook

Webhooks are used to notify clients when one of their recipients has completed the W-8BEN. The webhook payload includes W-8BEN data such as the recipient’s name, address, TIN(US/Foreign), as well as the link to download the completed form.

Go to Webhooks for information on Webhooks in TaxBandits.

Configure the Webhook for W-8BEN Status

  1. Log in to the developer console.

  2. Then navigate to Settings >> Webhooks.

  1. Click the Add Webhook button and choose the Event Type as W8BEN Status Change while setting up your Webhook URL.

Webhook Settings

Add Webhook

  1. After entering the Callback URL, click on the Submit button. Ensure that the callback URL is valid because the API will post a sample JSON. The callback URL is expected to return HTTP 200 response code in order to remain active. If the API doesn’t return 200 response code, then the callback URL will go inactive. You can retry posting the sample data to make the callback URL Active.

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission
RequesterobjectRequester information.
    BusinessIdGuidUnique identifier of a business
    BusinessNmStringRequester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    TINTypestringTIN Type of the Requester.
    TINstringTaxpayer Identification Number of the requester.
PayeeRefStringUnique identifier of the recipient
W8BENStatusStringStatus of the W-8BEN.
StatusTsStringTimestamp of the W-8BEN Status.
FormW8BENRequestTypeStringForm W-8BEN requested Type.
  • URL_API - Form W-8BEN was requested using the API method RequestByURL.
  • Email_API - Form W-8BEN was requested using the API method RequestByEmail.
  • Email_UI - Form W-8BEN was requested from the TaxBandits UI application.
PdfUrlStringURL to download the completed W-8BEN.
EmailStringEmail Address of the recipient. This is the email to which the W-8BEN request was sent.The value will be null if the Form W-8BEN was requested using the API method RequestByURL
FormDataObjectForm W-8BEN data of the recipient.
    NmOfIndividualstringName of the Foreign Individual.
    CitizenOfCountrystringRecipient country of citizenship.
    USTINTypestringTIN type of the recipient. Either SSN or ITIN.
    USTINstringRecipient’s TIN
    ForeignTINstringForeign TIN of the recipient.
    DOBstringDate of Birth of the recipient
    PermanentAddressObjectRecipient’s permanent address.
        Address1stringRecipient’s Address line 1
        Address2stringRecipient’s Address line 2
        CitystringRecipient’s City
        StatestringRecipient’s State
        CountrystringRecipient’s Country
        PostalCdstringRecipient’s Zip Code
    MailingAddressObjectRecipient’s mailing address.
        Address1stringRecipient’s Address line 1
        Address2stringRecipient’s Address line 2
        CitystringRecipient’s City
        StatestringRecipient’s State
        CountrystringRecipient’s Country
        PostalCdstringRecipient’s Zip Code
    TaxTreatyBenefitsObjectTax Treaty Benefits.
        BeneficiaryCountrystringCountry where the recipient claim to be a resident for income tax treaty purposes.
        ClaimingProvArticleParastringArticle and paragraph of the treaty benefits.
        RateOfWHstringRate of Withholding.
        TypeOfIncomestringType of income for which recipient claiming the treaty benefits.
        AdditionalConditionsstringAdditional conditions from the tax treaty benefits.
    SignatureObjectSignature of the recipient.
        SignerNmstringName of the signer.
        CapacityInWhichActingstringIf the form is signed by an agent on the person behalf, enter the capacity in which they are acting.
ErrorsObjectShows detailed error information.

Webhook Response

{   "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",   "Requester": {       "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",       "BusinessNm": "John Enterprises",       "TINType": "EIN",       "TIN": "22-2222222"        },   "PayeeRef": "7484391234545",   "W8BENStatus": "COMPLETED",   "StatusTs": "2021-02-19 14:36:28 -05:00",   "FormW8BENRequestType": "URL_API",   "PdfUrl":  "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",   "Email": "steve@abcinc.com",   "FormData": {       "NmOfIndividual": "Joseph Smith",       "CitizenOfCountry": "Canada",       "USTINType": "SSN",       "USTIN": "111-11-1111",       "ForeignTIN": null,       "DOB": "07/08/1990",   "PermanentAddress": {       "Address 1": "123",       "Address 2": "E. Main St",       "CityState": "Chennai,Tamilnadu",       "Country": "India",       "PostalCd": "29730"      },   "MailingAddress": {       "Address1": null,       "Address2": null,       "City": null,       "State": null,       "Country": null,       "PostalCd": null  },  "TaxTreatyBenefits": {      "BeneficiaryCountry": "Canada",      "ClaimingProvArticlePara": "VII",      "RateOfWH": "27.50",      "TypeOfIncome": "Royalties",      "AdditionalConditions": null },  "Signature": {      "SignerNm": "Joseph",      "CapacityInWhichActing": "Guardian"  },},"Errors": null,}