Web Messaging

TaxBandits API allows you to track W-9/W-8 submissions through webhooks or by calling the Status endpoint when using the RequestByEmail or RequestByBusinessUrl methods.

If you’re using the RequestByUrl method, you have an additional option: Web Messaging. This enables your application to receive instant notifications when a recipient completes and submits their form.

How web messaging works?

Web Messaging is a browser-based mechanism that enables cross-origin communication between a parent page and an embedded iframe. TaxBandits uses the window.postMessage feature to send a message from the iframe (child frame) back to your application (parent frame) once a form has been signed and submitted.

This event is triggered instantly after the W-9/W-8 form submission, allowing you to update your application’s UI in real time without waiting for webhook delivery or polling the status endpoint.

Note:

Web messaging can be set up for a particular account only upon request, and it won't be available by default. To enable web messaging, you can send an email to developer@taxbandits.com

The postMessage payload from the embedded TaxBandits iframe will include the following fields:

Sample Message :

{
"uid": "a465421b-c878-471a-8d0e-3b6912336b65",
"iat": "1516239022",
"Status": "Signed",
"PayeeRef": "TMG108687",
"FormType": "FORMW9"
}

Parameters:

Field	Description	Expected Values
uid	Unique identifier included in the iframe URL provided by TaxBandits in the RequestByUrl response	–
iat	Issued At Time (epoch time in UTC)	–
Status	Status of the submitted form	Signed, Cancelled
PayeeRef	Unique payee identifier provided in the original RequestByUrl API request	–
FormType	Type of form completed and submitted by the recipient	FORMW9, FORMW8BEN, FORMW8BENE

Debugging Tip

You can inspect the postMessage event using browser developer tools. In Chrome DevTools, open the Sources tab → look for Global Listeners on the right → select message to view incoming events.

Security measures

When handling postMessage events, it is important to validate the message source and content:

• Verify the origin — confirm the message is from a trusted TaxBandits domain.
• Match the UID — ensure the uid in the payload matches the UID received in the WHCertificate/RequestByUrl response.
• Validate the IAT — check the iat (Issued At Time) to confirm message integrity.

Note:

Refer to MDN documentation for secure use of postMessage.

The following sample script demonstrates how to receive the postMessage event from an embedded TaxBandits iframe in the parent frame:

<script type='text/javascript'>
// Create IE + others compatible event handler
var eventMethod = window.addEventListener ? "addEventListener" : "attachEvent";
var eventer = window[eventMethod];
var messageEvent = eventMethod == "attachEvent" ? "onmessage" : "message";
// Listen to message from child window
eventer(messageEvent,function(e) {
alert(e.data); // show the payload in alert
console.log('Message from TaxBandits!: ',e.data); // log the payload in console
},false);
</script>