Worklayer uses webhooks to notify your application of events happening in your workspace. You can react to events such as a Job being picked up by a Tax Pro, a document being added to a job, new messages being sent, or the job being completed. Check the Event Resources page for a full list of available events and payloads.

Worklayer uses HTTPS to deliver webhook notifications to your app as a JSON Payload. You can use these notifications in your backend to execute any actions you may deem appropirate.

1. Create a webhook endpoint as an HTTP endpoint on your server.
2. Handle requests from Worklayer by parsing each event and returning 2xx response status codes.
3. Secure your webhook by verifying signatures.

Set up an HTTP endpoint on your server that can accept unauthenticated webhook requests with a POST method in JSON format. For example, this route in an Node express.js app maps a webhook endpoint:

Copied
1const express = require('express');
2const bodyParser = require('body-parser');
3const app = express();
4
5app.post('/taxfyle_webhooks', bodyParser.json(), (request, response) => {
6  const event = request.body;
7});

Here, the /taxfyle_webhooks route is configured to accept POST requests and expect data in a JSON payload.

Your endpoint should be configured to read event resources for the type of event notifications you want to handle.

Review Event Structure

Webhook events have an object structure with the common top-level fields of id, create_time, event_type, version, and data. Your endpoint should check the event type and parse the payload of each event you care about.

Copied
1{
2  "id": "21e42d52-4145-465e-94bd-322c13bbe5fa",
3  "create_time": "2022-08-23T13:54:27.612477Z",
4  "event_type": "job.status",
5  "version": "1.0",
6  "data": {
7    "job": {} // The Job Resource
8  }
9}

Check the Events Resources page for all the available event types and their structure.

Return a 2xx response

Your endpoint should quickly return a sucessful status code (2xx) prior to any heavy computation that can cause a timeout.

Worklayer will retry for 4xx and 5xx status codes using a decorrelated jitter backoff strategy until a 2xx response is received.

During webhook setup, you'll receive a secret that can be used to verify incoming webhook requests in your endpoint. Worklayer generates a signature for each payload and includes information in the request headers that you can use to verify that the payloads were generated by Worklayer and not by another server acting as Worklayer.

Reference the Check Signagures page for complete details.

The following is a full example of reacting to a job.status event in Node.

Copied
1const express = require('express');
2const bodyParser = require('body-parser');
3const app = express();
4
5app.post('/taxfyle_webhooks', bodyParser.json(), (request, response) => {
6  const event = request.body;
7
8  switch (event.event_type) {
9    case 'job.status': 
10      const eventData = event.data;
11      // handleJobStatusChanged(eventData);
12      break;
13    default:
14      console.log(`Unhandled event type ${event.event_type}`);
15  }
16
17  // Return a response to acknowledge receipt
18  response.json({ok: true})
19});
20
21app.listen(8000, () => console.log('Running on port 8000'));