Skip to main content
Version: 1.7.0

Webhook

Webhooks are used to notify you regarding the status of W-9/W-8 completion by the recipients. The webhook payload includes W-9/W-8 data such as the recipient’s name, address, EIN/SSN, as well as the link to download the completed form.

For WhCertificate, you can add up to 5 Webhook URLs and choose the Callback URL to which the Webhook response needs to be posted.

To do that, store the unique reference we generate against each Callback URL at your end. Then, pass the reference in the request JSON. If the Webhook reference is not passed, we will post the Webhook response to the default Callback URL.

The webhook payload includes the recipient data, including the Name, Address, Country of citizenship, and TIN number, along with the link to download the completed Form W-9 or W-8BEN.

How does it work?

  1. Log in to the developer console.

  2. Then navigate to Settings >> Webhooks.

  3. To add multiple webhook Callback URLs inside the console site, click on the Add Webhook button.

Webhook Settings

  1. On the Add Webhook pop-up, choose the Event Type as WhCertificate Status Change. Once you select the event type, you will have the option to add up to 5 webhook Callback URLs.

WHCertificate Popup

  1. Upon Saving, TaxBandits generates a unique Webhook Reference (GUID) against each Callback URL. Store these Webhook References at your end and pass them in the request JSON for us to post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL (Callback URL 1).

WHCertificate Reference

WHCertificate CallBackUrls

6.When you call the WhCertificate/RequestByUrl endpoint, you can mention the preferred Callback URL by sending the stored Webhook Reference to the node WebhookRef. The WebhookRef node is optional.

When a recipient completes the W-9/W-8BEN, the webhook will be posted to the Callback URL that is tied to the WebhookRef given in the request.

If you do not specify the WebhookRef in the request, then the webhook will be posted to the default Callback URL.

Request JSON with WebhookRef

Sample Json

Response Body

FieldTypeDescription
FormTypeStringType of Form (W-9 or W-8BEN).
WebhookRefGuid
  • A unique identifier of the Webhook that TaxBandits generates against each Callback URL when adding it in the console site.
  • If you pass the WebhookRef in the request JSON, we will post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL.
FormW9ObjectContains Form W-9 Information.
    SubmissionIdGuidA unique identifier of a submission.
    RequesterObjectRequester information.
        BusinessIdGuidA unique identifier of the 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.
    PayeeRefStringA unique identifier of the recipient
    RecipientIdGuidA unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this ID for future reference to update.
    W9StatusStringStatus of the W-9
    StatusTsStringTimestamp of the W-9 Status
    TINMatchingObjectTIN Matching information.
        StatusStringTIN Matching status.
        StatusTsStringTimestamp of the TIN Matching Status.
        ErrorsStringShows the detailed error message.
    FormW9RequestTypeStringForm W-9 requested Type.
  • URL_API - Form W-9 was requested using the RequestByURL method.
  • Email_API - Form W-9 was requested using the RequestByEmail method.
  • Email_UI - Form W-9 was requested from the TaxBandits UI application.
    PdfUrlStringThe URL to download the completed W-9 .
Note: This URL will expire in 24 hours.
    EmailStringEmail Address of the recipient. This is the email to which the W-9 request was sent. The value will be null if the Form W-9 was requested using the RequestByURL method.
    FormDataObjectForm W-9 data of the recipient
        Line1NmstringName as shown on the income tax return
        Line2NmstringBusiness name/disregarded entity name, if different from Line1 Name
        TINTypestringTIN type of the recipient. (Either EIN or SSN)
        TINstringRecipient’s TIN
        AddressObjectRecipient’s complete address
            Address1stringRecipient’s Address 1 (number, street)
            Address2stringRecipient’s Address 2 (apt. or suite no.)
            CitystringRecipient’s City
            StatestringRecipient’s State
            ZipCdstringRecipient’s Zip Code
Size Range: 5..10
        FederalTaxClassificationstringU.S. Federal Tax Classification of the person whose name is entered on Line 1
        ExemptPayeeCdstringThis code identifies the recipient is exempt from backup withholding
        ExemptFromFATCAstringThis code identifies recipients that are exempt from reporting under FATCA.
        IsBackUpWHBoolean
  • When true, identifies the recipient is subject to backup withholding. The completed Form W-9 PDF will have the item 2 under Part II crossed out.
  • When false, identifies the recipient is not subject to backup withholding.
ErrorsObjectShows detailed error information.
FormW8BenObjectForm W-8BEN Information.
    SubmissionIdGuidA Unique identifier of a submission.
    RequesterObjectRequester information.
        BusinessIdGuidA unique identifier of the business.
        BusinessNmStringBusiness Name of the requester. 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.
    PayeeRefStringA Unique 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 RequestByURL method.
  • Email_API - Form W-8BEN was requested using the RequestByEmail method.
  • Email_UI - Form W-8BEN was requested from the TaxBandits UI application.
    PdfUrlStringThe URL to download the completed W-8BEN.
Note: This URL will expire in 24 hours.
    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 RequestByURL method.
    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.
            AddressstringRecipient’s Address.
            CitystringRecipient’s City
            StatestringRecipient’s State
            CountrystringRecipient’s Country
            PostalCdstringRecipient’s Zip Code
        MailingAddressObjectRecipient’s mailing address.
            AddressstringRecipient’s Address.
            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 claims 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 individual’s behalf, enter the capacity in which they are acting.
    ErrorsObjectShows detailed error information. Sample Webhook Response for W8Ben :

Scenario 1:No reference ID passed in node WebhookRef of the request. The recipient has completed Form W-8BEN, and the status has been changed to “Completed.” The payload will be posted to the default Callback URL, i.e., Callback URL 1. PdfUrl is provided to download the completed W-8BEN.

{
"FormType": "W8Ben",
"WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
"FormW9": null,
"FormW8Ben": {
"SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"PayerRef": null,
"BusinessNm": "Snowdaze LLC",
"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": "sample@bodeem.com",
"FormData": {
"NmOfIndividual": "Joseph Smith",
"CitizenOfCountry": "Canada",
"USTINType": "SSN",
"USTIN": "111-11-1111",
"ForeignTIN": null,
"DOB": "07/08/1990",
"PermanentAddress": {
"Address": "123 E. Main St",
"City": "Rock Hill",
"State": "SC",
"Country": "USA",
"ZipCd": "29730"
},
"MailingAddress": {
"Address": null,
"City": null,
"State": null,
"Country": null,
"ZipCd": null
},
"TaxTreatyBenefits": {
"BeneficiaryCountry": "Canada",
"ClaimingProvArticlePara": "VII",
"RateOfWH": "27.50",
"TypeOfIncome": "Royalties",
"AdditionalConditions": null
},
"Signature": {
"SignerNm": "Joseph",
"CapacityInWhichActing": "Guardian"
}
},
"Errors": null
},
"Errors": null
}

Scenario 2: No reference ID passed in node WebhookRef of the request. The recipient has completed Form W-9, and TIN Matching is in progress. The payload will be posted to the default Callback URL, i.e., Callback URL 1.

{
"FormType": "FormW9",
"WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
"FormW9": {
"SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",
"Requester": {
"BusinessId": "fb6ddd28-ad30-4fc2-bd17-38a937f2aa81",
"PayerRef": null,
"BusinessNm": "Snowdaze LLC",
"TINType": "EIN",
"TIN": "XX-XXX2222"
},
"PayeeRef": "Pe123451234",
"RecipientId": "sdf3ccee-10d8-4eb4-ab81-234234c9636",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-06-24 10:40:21 -04:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-06-24 10:40:21 -04:00",
"StatusMsg": null,
"Errors": null
},
"FormW9RequestType": "Email_API",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "sample@bodeem.com",
"FormData": {
"Line1Nm": "ABC Inc",
"Line2Nm": null,
"TINType": "EIN",
"TIN": "XX-XXX1111",
"Address": {
"Address1": "123 E. Main St",
"Address2": "Suite 400",
"City": "Rock Hill",
"State": "SC",
"ZipCd": "29730"
},
"FederalTaxClassification": "C Corporation",
"ExemptPayeeCd": "5",
"ExemptFromFATCA": "F",
"IsBackUpWH": false
},
"Errors": null
},
"FormW8Ben": null,
"Errors": null
}