Webhooks Best Practices

To avoid webhook requests potentially stressing your system, WorkOS strongly recommends that you respond to a webhook request with a 200 OK as quickly as possible once received.

If you process the event before responding, your system may not be able to handle a spike of requests. This may cause requests to timeout and result in missing important updates.

A common pattern is to store the request payload on a message queue, respond with a 200 OK, and use a background worker to process the messages in the queue.

If your endpoint fails to respond to a webhook request with a 2xx response, WorkOS will automatically retry the event with exponential back-off for up to 3 days in production environments. If for some reason your endpoint is still unable to respond successfully to events during that period, the event will be considered failed, and we will no longer retry sending it. You can reconcile your data using our Directory Sync endpoints to update your data.

WorkOS does not guarantee that events are delivered in the same sequence that they are generated. For example, when syncing a directory you may receive:

Your endpoint should handle cases when these events are delivered out of order. Each event includes the full payload of the objects involved, so you can perform an upsert using the payload data.

It is also possible that event data can be stale due to a retry of an older event being delivered after a newer event for the same object. Therefore, we recommend checking the timestamp of the incoming webhook data against the timestamp of the data in your system to ensure you do not overwrite your data with stale data. Each object in the payload includes a created_at field and an updated_at field.

It is possible to receive the same event more than once. WorkOS recommends that you handle webhook events using idempotent operations. One way of doing this is logging the ID of webhook events that you have processed and ignoring subsequent requests with the same ID.

WorkOS sends webhook events for four main categories: connections, directories, directory groups and directory users. Your webhook endpoints should only be configured to receive the ones required by your integration. Receiving all event types can put undue strain on your servers and is not recommended.

In the WorkOS Dashboard you can create multiple endpoints for receiving webhooks. For each webhook endpoint, you can specify the types of events it would receive.

Ensuring that your webhook endpoint is secure is critical to protecting your customers’ data. WorkOS recommends several measures to do this.

Before processing the request payload, verify the request was sent by WorkOS and not an unknown party.

WorkOS includes a unique signature in each webhook request that it sends, allowing you to verify the authenticity of the request. In order to verify this signature, you must obtain the secret that is generated for you when you set up your webhook endpoint in the WorkOS dashboard. Ensure that this secret is stored securely on your webhook endpoint server as an environment variable.

The WorkOS SDKs have methods for validating the timestamp and signature of a webhook. Examples using these methods are included below. The parameters are the payload (raw request body), the WorkOS-Signature header, and the webhook secret. There is an optional parameter, tolerance, that sets the time validation for the webhook in seconds. The SDK methods have default values for tolerance, usually 3-5 minutes.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const webhook = workos.webhooks.constructEvent({
  payload: payload,
  sigHeader: sigHeader,
  secret: process.env.WEBHOOK_SECRET,
});

If implementing webhook validation yourself, you’ll need to use the following steps:

First, extract the timestamp and signature from the header. There are two values to parse from the WorkOS-Signature, delimited by a , character:

To avoid replay attacks, we suggest validating that the issued_timestamp does not differ too much from the current time.

Next, construct the expected signature. The expected signature is computed from the concatenation of:

Hash the string using HMAC SHA256, using the webhook secret as the key. The expected signature will be the hex digest of the hash. Finally, compare signatures to make sure the webhook request is valid.

Once you’ve determined the event request is validly signed, it’s safe to use the event, i.e. the request body, in your application’s business logic. You do not need to signal to WorkOS whether or not the event was processed successfully.

A small security measure you can incorporate is to make your webhook endpoint difficult to guess. Including a token comprised of series of random numbers and letters to your endpoint URL can prevent malicious actors from easily guessing your endpoint. For example: https://api.foo-corp.com/webhooks/n0dbga5x... is much more difficult to guess than https://api.foo-corp.com/webhooks

WorkOS sends webhooks from a fixed set of IP addresses. If you are looking to create a list of allowed IP addresses for webhooks, use these IP addresses:

3.221.3.224
54.144.9.196
54.172.232.96
52.87.96.186

From the WorkOS Dashboard, you can send test webhook events after configuring an endpoint. From the webhook endpoint detail screen, click the “Actions” button and select “Send Test event”. The types of events that you have configured for your endpoint are available for you to send sample payloads.

If you would like to test against your local development environment, we recommend using a tool like ngrok to create a secure tunnel to your local machine, and sending test webhooks to the public endpoint generated with ngrok. See our blog post to get more details on how you may want to test webhooks locally with ngrok.