Web Messaging (postMessage)

Web messaging is an additional notification mechanism available when using the RequestByUrl,RequestByEmail,RequestByBusinessUrl method with the form embedded as an iframe. It enables your parent application to receive an instant browser-level notification the moment a recipient submits their form — without waiting for a webhook delivery or polling the Status endpoint.

How it works

TaxBandits uses the browser's native window.postMessage API to send a message from the embedded iframe (child frame) to your application's page (parent frame) immediately after the form is signed and submitted. Your application listens for this event and can update the UI in real time.

Web messaging is not enabled by default. To activate it for your account, contact developer@taxbandits.com.

Message payload

The postMessage event includes the following fields:

Field	Description	Example values
uid	Unique identifier from the RequestByUrl response URL.	a465421b-c878-471a-8d0e
iat	Issued-at timestamp in Unix epoch (UTC).	1516239022
Status	Result of the form submission.	Signed, Canceled
PayeeRef	The PayeeRef value passed in the original API request.	TMG108687
FormType	The form type the recipient completed.	FORMW9, FORMW8BEN, FORMW8BENE

Here is a sample message:

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

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 requirements

When handling postMessage events, always validate the incoming message before acting on it:

• Verify the message origin to confirm it comes from a trusted TaxBandits domain.
• Match the uid in the payload against the UID received in the original RequestByUrl response.
• Validate the iat timestamp to confirm message freshness and integrity.

Refer to MDN documentation for secure implementation guidance.

Sample Script

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>