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.

   • Sandbox Console URL: sandbox.taxbandits.com
   • Live Console URL: console.taxbandits.com

2. Then navigate to Settings >> Webhooks.

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

4. 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.

5. 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).

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

Response Body

Field	Type	Description
FormType	String	Type of Form (W-9 or W-8BEN).
WebhookRef	Guid	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.
FormW9	Object	Contains Form W-9 Information.
SubmissionId	Guid	A unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
BusinessNm	String	Requester 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.
TINType	String	TIN Type of the Requester.
TIN	String	Taxpayer Identification Number of the requester.
DBAId	String	Unique Identifier for the DBA.
DBARef	String	Unique identifier for each DBA. This identifier can be used in future references of the DBA in the API.
PayeeRef	String	A unique identifier of the recipient
RecipientId	Guid	A 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.
W9Status	String	Status of the W-9
StatusTs	String	Timestamp of the W-9 Status
TINMatching	Object	TIN Matching information.
Status	String	TIN Matching status.
StatusTs	String	Timestamp of the TIN Matching Status.
Errors	String	Shows the detailed error message.
FormW9RequestType	String	Form 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.
PdfUrl	String	The URL to download the completed W-9. Note: This URL will expire in 24 hours.
Email	String	Email 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.
FormData	Object	Form W-9 data of the recipient
Line1Nm	string	Name as shown on the income tax return
Line2Nm	string	Business name/disregarded entity name, if different from Line1 Name
TINType	string	TIN type of the recipient. (Either EIN or SSN)
TIN	string	Recipient’s TIN
Address	Object	Recipient’s complete address
Address1	string	Recipient’s Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Address2	string	Recipient’s Address 2 (suite or apartment number). This will be pre-filled on the Form.
City	string	Recipient’s City
State	string	Recipient’s State
ZipCd	string	Recipient’s Zip Code Size Range: 5..10
AccountNum	string	Recipient’s account number. You can use this field to enter any identification number you have for the recipient.
FederalTaxClassification	string	U.S. Federal Tax Classification of the person whose name is entered on Line 1
IsLine3b	Boolean	If TRUE, identifies that the recipient is Either a partnership, trust or estate that has foreign partners, owners, or beneficiaries and the recipient is providing this form to a partnership, trust, or estate, in which they have an ownership interest. (or) Received a Form W-8 from any partner, owner, or beneficiary establishing foreign status (or) Received a Form W-9 from any partner, owner, or beneficiary that has checked the box on line 3b.
ExemptPayeeCd	string	This code identifies the recipient is exempt from backup withholding
ExemptFromFATCA	string	This code identifies recipients that are exempt from reporting under FATCA.
IsBackUpWH	Boolean	If True identifies that the recipient have been notified by the Internal Revenue Service (IRS) that they are subject to backup withholding.
Errors	Object	Shows detailed error information.
FormW8Ben	Object	Form W-8BEN Information.
SubmissionId	Guid	A Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
BusinessNm	String	Business Name of the requester. If the requester is an Individual, then the Payer’s full name will be returned.
TINType	String	TIN Type of the Requester.
TIN	String	Taxpayer Identification Number of the requester.
PayeeRef	String	A Unique identifier of the recipient
W8BENStatus	String	Status of the W-8BEN.
StatusTs	String	Timestamp of the W-8BEN Status.
FormW8BENRequestType	String	Form 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.
PdfUrl	String	The URL to download the completed W-8BEN. Note: This URL will expire in 24 hours.
Email	String	Email 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.
FormData	Object	Form W-8BEN data of the recipient.
NmOfIndividual	string	Name of the Foreign Individual.
CitizenOfCountry	string	Recipient country of citizenship.
USTINType	string	TIN type of the recipient. (Either SSN or ITIN)
USTIN	string	Recipient’s TIN
ForeignTIN	string	Foreign TIN of the recipient.
IsFTINNotLegallyRequired	Boolean	When true, Identifies that beneficial owner on line 1 is not legally required to obtain an FTIN from their jurisdiction of residence.
ReferenceNum	string	Recipient’s reference number. You can use this field to enter any identification number you have for the recipient.
DOB	string	Date of Birth of the recipient
PermanentAddress	Object	Recipient’s permanent address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
MailingAddress	Object	Recipient’s mailing address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
TaxTreatyBenefits	Object	Tax Treaty Benefits.
BeneficiaryCountry	string	Country where the recipient claim to be a resident for income tax treaty purposes
ClaimingProvArticlePara	string	Article and paragraph of the treaty benefits
RateOfWH	string	Rate of Withholding.
TypeOfIncome	string	Type of income for which recipient claims the treaty benefits.
AdditionalConditions	string	Additional conditions from the tax treaty benefits.
Signature	Object	Signature of the recipient.
SignerNm	string	Name of the signer.
CapacityInWhichActing	string	If the form is signed by an agent on the individual’s behalf, enter the capacity in which they are acting.
Errors	Object	Shows detailed error information.

Sample Webhook Response :

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": "FormW8Ben",
  "WebhookRef": "47ad4e81-6761-46ba-ab27-439333532b58",
  "FormW9": null,
  "FormW8Ben": {
    "SubmissionId": "dae58d03-604b-4fa6-a89d-40a8c07962f2",
    "Requester": {
      "BusinessId": "ecef4552-34cf-4b65-aae8-ac74bc1ec484",
      "PayerRef": "Pay140054",
      "BusinessNm": "Snowdaze LLC",
      "FirstNm": null,
      "MiddleNm": null,
      "LastNm": null,
      "Suffix": null,
      "TINType": "EIN",
      "TIN": "XX-XXX8383",
      "DBAId": null,
      "DBARef": null
    },
    "PayeeRef": "abc34352",
    "RecipientId": null,
    "W8BENStatus": "COMPLETED",
    "StatusTs": "2024-07-30 03:43:05 -04:00",
    "FormW8BENRequestType": "COMMON_URL_API",
    "PdfUrl": "https://s3.amazonaws.com/taxbandits-sb-api/1296eb81-eade-4c74-a094-c1d5376ed933.Pdf",
    "Email": null,
    "FormData": {
      "NmOfIndividual": "Shawn Willams",
      "CitizenOfCountry": "Canada",
      "USTINType": null,
      "USTIN": null,
      "ForeignTIN": null,
      "IsFTINNotLegallyRequired": true,
      "ReferenceNum": null,
      "DOB": null,
      "PermanentAddress": {
        "Address1": "120 Bremner Blvd",
        "Address2": "Suite 800",
        "City": "Toronto",
        "ProvinceOrStateNm": "Ontario",
        "Country": "Canada",
        "PostalCd": "4168682600"
      },
      "MailingAddress": {
        "Address1": "120 Bremner Blvd",
        "Address2": "Suite 800",
        "City": "Toronto",
        "ProvinceOrStateNm": "Ontario",
        "Country": "Canada",
        "PostalCd": "4168682600"
      },
      "TaxTreatyBenefits": {
        "BeneficiaryCountry": null,
        "ClaimingProvArticlePara": null,
        "RateOfWH": "0.0",
        "TypeOfIncome": null,
        "AdditionalConditions": null
      },
      "Signature": {
        "SignerNm": "Shawn Willams"
      }
    },
    "Errors": null
  },
  "FormW8BenE": 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": "db8ff0f9-e53e-4549-809d-2329c66e6bbc",
  "FormW9": {
    "SubmissionId": "6db06adc-d5e6-4d19-8e28-26b7209ebcaa",
    "Requester": {
      "BusinessId": "385ccd75-3ec5-47a1-b6dc-18faeaeb7d95",
      "PayerRef": null,
      "BusinessNm": "Snowdaze LLC",
      "FirstNm": null,
      "MiddleNm": null,
      "LastNm": null,
      "Suffix": null,
      "TINType": "EIN",
      "TIN": "39-4589707",
      "DBAId": null,
      "DBARef": null
    },
    "PayeeRef": "Pay465",
    "RecipientId": "289fc850-8f42-49b4-a451-9c81586a3ea8",
    "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
    "StatusTs": "2024-07-30 05:12:17 -04:00",
    "TINMatching": {
      "Status": "ORDER_CREATED",
      "StatusTs": "2024-07-30 05:12:18 -04:00",
      "StatusMsg": null,
      "Errors": null
    },
    "FormW9RequestType": "COMMON_URL_API",
    "PdfUrl": "https://s3.amazonaws.com/taxbandits-sb-api/bea0f55f-b3ec-451b-93b9-cfc33cbbad31.Pdf",
    "Email": "shawn@sample.com",
    "FormData": {
      "Line1Nm": "Delights LLC",
      "Line2Nm": "lights ",
      "FirstNm": null,
      "MiddleNm": null,
      "LastNm": null,
      "Suffix": null,
      "TINType": "EIN",
      "TIN": "64-6234623",
      "Address": {
        "Address1": "71 SAINT NICHOLAS DR",
        "Address2": null,
        "City": "NORTH POLE",
        "State": "AK",
        "ZipCd": "99705-7752"
      },
      "AccountNum": "65893256",
      "FederalTaxClassification": "C Corporation",
      "IsLine3b": false,
      "ExemptPayeeCd": "1",
      "ExemptFromFATCA": "F",
      "IsBackUpWH": true
    },
    "Errors": null
  },
  "FormW8Ben": null,
  "FormW8BenE": null
}