@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/email.mdx

@@ -0,0 +1,109 @@
+---
+title: Email delivery
+description: Best practices for sending email with WorkOS.
+breadcrumb:
+  title: Home
+  url: /
+originalPath: .tmp-workos-clone/packages/docs/content/email.mdx
+---
+
+## Introduction
+
+Many WorkOS features rely on your users receiving and acting upon email. For example, this includes invitations to join your app, password reset links, or Magic Auth sign-in. Prompt delivery of these emails is crucial.
+
+WorkOS offers three options for sending email:
+
+- **WorkOS email domain:** WorkOS sends email from the `workos-mail.com` domain.
+- **Your email domain:** WorkOS sends email from your own email domain.
+- **Send your own email:** WorkOS emits events, allowing your app to listen to these events and send email using your own email provider.
+
+These options provide different trade-offs between convenience, customization, and control over email deliverability.
+
+WorkOS follows industry best practices when sending email. SPF and DKIM email authentication records are configured automatically, the email content is continually refined to ensure it passes spam filters, and delivery of every email is actively monitored. However, regardless of the option you chose for sending email to your users, there are additional steps you can take to ensure that it reaches user inboxes.
+
+---
+
+## (A) WorkOS email domain
+
+By default WorkOS will send the following emails from the `workos-mail.com` domain in production environments.
+
+| Email              | Sent From               | Purpose                                |
+| ------------------ | :---------------------- | :------------------------------------- |
+| Invitation         | welcome@workos-mail.com | Invite a user to create an account     |
+| Magic Auth         | access@workos-mail.com  | Allow sign in with a one-time-use code |
+| Email verification | welcome@workos-mail.com | Verify ownership of a given email      |
+| Password reset     | access@workos-mail.com  | Support the password reset flow        |
+
+WorkOS has configured SPF, DKIM and DMARC email authentication records for the `workos-mail.com` domain. These records prove to the receiving mail server that a given email comes from WorkOS.
+
+We actively monitor the delivery of email sent from the `workos-mail.com` domain to protect the domain's reputation. If we detect unusually high rates of undelivered mail or mail marked as spam from a WorkOS team account, we may suspend that team's ability to send email.
+
+### Do not send unsolicited email
+
+To ensure email is delivered when using the WorkOS email domain, be sure not to allow unsolicited email to be sent on your behalf. For example, an invitation email should be sent only if a user explicitly requests access to your application for themselves or another user. Do not attempt to bulk invite users from an email marketing list.
+
+### Use appropriate team and organization names
+
+It is also important to ensure that your WorkOS team account and all organizations under your team have appropriate names that avoid [common spam words](https://mailtrap.io/blog/email-spam-words/) that may trigger spam filters. While our static email content is thoroughly tested, WorkOS emails can include your team name as well as the names of organizations under your team. There may be an impact to email deliverability if these names use terms often flagged by spam filters.
+
+---
+
+## (B) Your email domain
+
+While using the WorkOS email domain option is convenient, you can provide your users a better experience. Using your own email domain means that your users will receive emails from a domain they recognize, one associated with your app. In addition, because you control the email domain, you have more control over the domain reputation and therefore more control over email deliverability.
+
+You can configure your own email domain in the [WorkOS dashboard](https://dashboard.workos.com). You will need to verify ownership of the domain by setting up a CNAME record with your domain provider. Two additional CNAME records are required to automatically configure SPF and DKIM email authentication using [Sendgrid's automated security feature](https://support.sendgrid.com/hc/en-us/articles/21415314709147-Email-Authentication-SendGrid-s-Automated-Security-Explained).
+
+![Configuring your email domain](https://images.workoscdn.com/images/84e47c58-e5e5-47c3-8245-f414a203f284.png?auto=format&fit=clip&q=50)
+
+In addition to not sending unsolicited emails and using appropriate team and organization names, when using your own email domain there are a few additional steps you can take to ensure email is delivered promptly.
+
+### Set up inboxes
+
+When using your own domain, email will be sent from `welcome@<your domain>` and `access@<your domain>`. Email providers check if there are inboxes associated with sender addresses, so setting up inboxes for both the `welcome` and `access` email addresses on your domain can help ensure your emails reach users.
+
+### Set up DMARC
+
+WorkOS recommends that you set up DMARC (Domain-based Message Authentication, Reporting & Conformance) with your domain provider. Google has released [guidelines](https://support.google.com/a/answer/81126?visit_id=638529785140327067-2643207201&rd=1#zippy=%2Crequirements-for-all-senders%2Crequirements-for-sending-or-more-messages-per-day) for email senders and the guidelines include DMARC requirements. Apple and Yahoo have released similar best practice guides.
+
+A DMARC policy tells a receiving mail server what to do when a message from your domain doesn’t pass DMARC authentication. Configuring DMARC requires setting up a DNS TXT record with your domain provider.
+
+Here is an example DMARC record that will reject all emails not legitimately sent by an email provider on your behalf:
+
+```plaintext
+TXT Record
+
+name:
+_dmarc<.example.com>
+
+content:
+v=DMARC1; p=reject; rua=mailto:postmaster@example.com, mailto:dmarc@example.com; pct=100; adkim=s; aspf=s
+```
+
+More details about DMARC can be found at [dmarc.org](https://dmarc.org/overview/).
+
+---
+
+## (C) Send your own email
+
+There are a number of reasons why you may want to send email using your own email provider. Perhaps you already send a welcome email to new users and want to include an invitation link instead of sending a second email. Perhaps you want to translate the email text into different languages. Perhaps you already track sent email status with your own email provider and want a unified view into the status of all emails associated with your app. Regardless, when you send your own email, you have complete control over email deliverability.
+
+For complete instructions on sending your own email, see the section on [custom emails](/user-management/custom-emails) in the user management documentation.
+
+When sending your own email, you will want to follow the all of the recommendations in Google's [email sender guidelines](https://support.google.com/a/answer/81126?hl=en). This includes setting up SPF, DKIM and DMARC email authentication.
+
+You will also need to be conscious of your sender reputation. It's based on the quality of emails, their frequency, and user interaction. A good sender reputation can increase the chances of your emails reaching inboxes. Sendgrid provides some [useful tips for improving sender reputation](https://sendgrid.com/en-us/blog/email-reputation-101-ip-reputation-vs-domain-reputation).
+
+If you author your own email content, you may want to test your emails against various email providers' spam filters. There are a number of spam testing services available such as [Litmus](https://www.litmus.com/email-testing) and [Warmly](https://www.warmy.io/free-tools/email-deliverability-test/).
+
+---
+
+## Troubleshooting
+
+Even when following industry best practices, an email may get filtered as spam and not reach a user's inbox. Other times an email might be delayed, for example, when [Enhanced Pre-delivery Message Scanning](https://apps.google.com/supportwidget/articlehome?hl=en&article_url=https%3A%2F%2Fsupport.google.com%2Fa%2Fanswer%2F7380368%3Fhl%3Den&product_context=7380368&product_name=UnuFlow&trigger_context=a) is enabled on a Google workspace or when a similar feature is enabled with other email providers. Email providers do not explain the heuristics used by their spam filters and security mechanisms, and they are often changing, making it especially frustrating to troubleshoot problems.
+
+The first step in troubleshooting is to determine if the problem exists for all users or only a subset of users. Generally, this will provide insight into the nature of the issue and how best to resolve it. If the issue exists for all users, it is most likely a matter of poor domain reputation. If the issue only exists for a subset of users, it may be because of specific settings used by an email provider or the IT department at a given organization.
+
+Both Google and Microsoft have been noted as being especially aggressive when identifying spam. However, both companies provide some tooling to help you debug email deliverability problems. Google offers [Postmaster Tools](https://www.gmail.com/postmaster/) to help with email deliverability related to Gmail and Google Workspaces. Microsoft offers similar tools with [Sender Support](https://sendersupport.olc.protection.outlook.com/pm/). Lastly, more general spam testing services such as [Litmus](https://www.litmus.com/email-testing) and [Warmly](https://www.warmy.io/free-tools/email-deliverability-test/) are available.
+
+If you continue to have issues regarding email deliverability despite following all of the above suggestions, please [contact support](mailto:support@workos.com).

package/.docs/organized/docs/events/_navigation.mdx

@@ -0,0 +1,22 @@
+---
+title: Events
+links:
+  - title: Event types
+    url: /events
+  - title: Data syncing
+    links:
+      - title: Overview
+        url: /events/data-syncing
+      - title: Syncing with events API
+        url: /events/data-syncing/events-api
+      - title: Syncing with webhooks
+        url: /events/data-syncing/webhooks
+      - title: Data reconciliation
+        url: /events/data-syncing/data-reconciliation
+  - title: Observability
+    links:
+      - title: Streaming to Datadog
+        url: /events/observability/datadog
+originalPath: .tmp-workos-clone/packages/docs/content/events/_navigation.mdx
+---
+

package/.docs/organized/docs/events/data-syncing/data-reconciliation.mdx

@@ -0,0 +1,56 @@
+---
+title: Data reconciliation
+description: Keep your app in sync with WorkOS.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/events/data-syncing/data-reconciliation.mdx
+---
+
+## Introduction
+
+While the events API makes it easier to keep your app in sync with WorkOS, there may still be cases where your app gets out of sync. For example, your app may have a bug in its event processing logic or in rarer cases, may experience some data loss.
+
+Data reconciliation refers to the process of comparing and aligning the state of objects between WorkOS and your app to ensure consistency. Depending on the scope of the issue, you can reconcile your app state by either replaying events from the [events API](/reference/events) or by using the WorkOS [state API](/reference).
+
+## Definitions
+
+**Data reconciliation**
+: Refers to the process of comparing and aligning data from different sources or systems to ensure consistency and accuracy. The goal of data reconciliation is to ensure that all relevant data sources are synchronized and reflect the same information.
+
+**Event replay**
+: Is the act of reprocessing recorded events in an app. It is used to recreate past event sequences for debugging, testing, auditing, or ensuring data consistency.
+
+**Side effects**
+: These are secondary consequences that arise from data modifications in an app. They can alter related data, trigger additional processes, update external systems, or affect the app’s overall state. e.g., Sending an email on a user’s profile change.
+
+**Periodic reconciliation**
+: Is the regular process of comparing and synchronizing data between systems to ensure accuracy and consistency. It involves scheduled checks to identify and resolve discrepancies in data integrity.
+
+## Reconciling via the events API
+
+In general, reconciling state changes between WorkOS and your app using the events API is simplest. Pick your cursor, which is usually the last known cursor you have processed, and paginate through events using the `after` parameter.
+
+For special cases such as webhook migration or event replay, you can specify a starting time for event consumption using the `range_start` parameter.
+
+### Handling side effects in the case of event replay
+
+Side effects, such as sending emails, updating 3rd party APIs, or performing other actions specific to your app, present challenges during event replay.
+
+Separating data handling from business logic allows you to exercise control over what actions you want your app to make. This allows your app to replay events to sync data but bypass transactional logic e.g., not sending out the same email twice.
+
+## Reconciling via the WorkOS state API
+
+Your app may perform data reconciliation by syncing state via the WorkOS [state APIs](/reference) e.g., in disaster recovery scenarios.
+
+Data reconciliation using state APIs requires performing diffs to identify deletions to ensure the correct state is maintained. This introduces additional complexity, making it essential to carefully design and test the reconciliation process.
+
+The general approach for reconciling data via the state API is as follows:
+
+1. Pull state from WorkOS API for the objects your app is interested in.
+2. Update based on `updated_at`. If the timestamp is out of date, update the object.
+3. Identify deactivated objects or deletions and sync that state.
+
+If you need to force all objects to update state, perform a complete resynchronization of the affected data instead of relying solely on the `updated_at` timestamp. Update all objects regardless of the individual `updated_at` timestamp.
+
+### Considerations for periodic reconciliation
+
+In some cases, you may want to run periodic reconciliation jobs to proactively check and reconcile the state between WorkOS and your app. When implementing such jobs, it is important to account for potential race conditions for concurrent updates. Additionally, consider the specific characteristics of your app to determine the frequency and scope of periodic reconciliation.

package/.docs/organized/docs/events/data-syncing/events-api.mdx

@@ -0,0 +1,114 @@
+---
+title: "Sync data using the events\_API"
+description: "A step-by-step guide on how to start syncing data using the\_API."
+originalPath: .tmp-workos-clone/packages/docs/content/events/data-syncing/events-api.mdx
+---
+
+## What you’ll build
+
+In this guide, we will walk you through what you will need to integrate with the [events API](/reference/events):
+
+- Create a _cursor_ for use with the events API
+- Update your cursor
+- Choose a cursor if you lose yours
+- Handle event replay in your app
+
+## Before getting started
+
+To get the most out of this guide, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+- An [SSO](/sso/1-add-sso-to-your-app) or [directory](/directory-sync/quick-start/1-create-a-new-directory-connection) connection configured in order to generate events
+
+---
+
+## (1) Integrate the events API SDK
+
+WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your app’s language.
+
+<LanguageSelector languages={['js', 'ruby', 'python', 'go']}>
+  Install the SDK using the command below.
+
+  <CodeBlock title="Install the WorkOS SDK" file="install-sdk">
+    <CodeBlockTab language="js" file="install-sdk-npm" title="npm" />
+    <CodeBlockTab language="js" file="install-sdk-yarn" title="Yarn" />
+    <CodeBlockTab language="ruby" file="install-sdk-terminal" title="Terminal" />
+    <CodeBlockTab language="ruby" file="install-sdk-bundler" title="Bundler" />
+  </CodeBlock>
+</LanguageSelector>
+
+### Set secrets
+
+To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences.
+
+```plain title="Environment variables"
+WORKOS_API_KEY='sk_example_123456789'
+WORKOS_CLIENT_ID='client_123456789'
+```
+
+> The code examples use your staging API keys when [signed in](https://dashboard.workos.com)
+
+---
+
+## (2) Start consuming events
+
+Your app can start consuming events once it integrates the WorkOS SDK. The first thing to do is to pick a starting place in the data set.
+
+### Keep a cursor
+
+A _cursor_ is a bookmark to track your app’s position in the events list. The very first call to the events API won’t have a cursor. Subsequent requests to WorkOS should include the updated cursor using the `after` parameter. You will need to update and store your cursor after processing an event.
+
+### Avoid overwriting newer data
+
+To avoid repeating an update, store the `updated_at` timestamp provided by WorkOS for each object. Extract this tag from the data object in the event. If the `updated_at` timestamp in the event is newer, update the local state with the latest event data. Otherwise, you can skip processing that event.
+
+---
+
+## (3) Select event types
+
+Determine the [event types](/events) you want to consume. Choose the relevant event types that align with your app’s functionality and integration with WorkOS.
+
+<CodeBlock title="List events" file="list-events" />
+
+Retrieve events from the API using cursor pagination. To fetch the next set of events, provide the ID of the latest processed event in the `after` parameter.
+
+---
+
+## (4) Handle event replay
+
+In some cases, it may be necessary to go back in time and “replay” the events. When designing your app logic to handle events replay it is important to design your event handling logic in a way that can safely accommodate it without undesired effects.
+
+To achieve this, focus on separating your app’s data handlers from transactional business logic like sending emails, communicating to 3rd party APIs, etc. By implementing separate data handling, you can replay events without side effects.
+
+WorkOS recommends processing events synchronously, handling them in the order they occurred.
+
+> The events API returns events up to 90 days old. You can query for up to 30 days of events per request.
+
+### If your app stops processing events
+
+When resuming event processing, you have two options to pick up where you left off:
+
+- **Using the latest known cursor:** Retrieve the most recent cursor that was successfully processed and use it as the starting point for event resumption.
+- **Using a timestamp:** Alternatively, you can make an API call with the `range_start` parameter and then use the cursor. Utilize the `updated_at` timestamp to prevent overwrites.
+
+---
+
+## Scaling recommendations
+
+### Single consumer
+
+WorkOS recommends that your app starts with a single worker. Process events in a separate thread or process from your app’s main execution thread. Deploying a single worker responsible for handling events simplifies and streamlines event consumption.
+
+This approach ensures serial event processing. After completing the processing of events on the current page, request the next page of events to maintain progress.
+
+### Parallel processing
+
+For onboarding large organizations, divide events into independent queues for parallel processing when calling the events API from a single worker.
+
+Concurrently processing events from different organizations is safe, but for consistency and integrity, it is recommended to sequentially process events within a single organization.
+
+---
+
+## Migrating from webhooks
+
+You can migrate to the events API if you already use webhooks. To migrate, start querying the events API using the `range_start` parameter that corresponds to the time you’d want to start syncing from. The event IDs passed in webhook bodies are the same as those returned by the events API.

package/.docs/organized/docs/events/data-syncing/index.mdx

@@ -0,0 +1,66 @@
+---
+title: Data syncing
+description: Keep your app in sync with WorkOS.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/events/data-syncing/index.mdx
+---
+
+## Introduction
+
+Syncing your app data with WorkOS is done using events. Events represent activity that has occurred within WorkOS or within third-party identity and directory providers that interact with WorkOS.
+
+When important activity occurs, we record an event. For example, a new SSO connection being activated is an event. A user being created, assigned membership to an organization, or successfully signing in are all events as well. Events are activity that your application might be interested in for the purposes of syncing data or extending your application's business logic.
+
+Your app can consume events from WorkOS via either the events API or webhooks.
+
+```json language="json" title="A sample event"
+{
+  "object": "event",
+  "id": "event_07FKJ843CVE8F7BXQSPFH0M53V",
+  "event": "dsync.user.updated",
+  "data": {
+    "id": "directory_user_01E1X1B89NH8Z3SDFJR4H7RGX7",
+    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
+    "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
+    "idp_id": "8931",
+    "first_name": "Lela",
+    "last_name": "Block",
+    "email": "lela.block@example.com",
+    "state": "active",
+    "created_at": "2021-06-25T19:07:33.155Z",
+    "updated_at": "2021-06-25T19:07:33.155Z",
+    "custom_attributes": {
+      "department": "Engineering",
+      "job_title": "Software Engineer"
+    },
+    "role": { "slug": "member" },
+    "raw_attributes": {}
+  },
+  "created_at": "2023-04-28 20:05:31.093"
+}
+```
+
+---
+
+## Sync using the events API
+
+With the events API, your application retrieves events from WorkOS. The events API offers a more robust data synchronization solution compared to webhooks, ensuring seamless synchronization of your system state with WorkOS. To sync data using the events API, continue to the [events API guide](/events/data-syncing/events-api).
+
+---
+
+## Sync using webhooks
+
+With webhooks, WorkOS automatically notifies your app when an event occurs by invoking an endpoint hosted within your application. To sync data using webhooks, continue to the [webhooks guide](/events/data-syncing/webhooks).
+
+---
+
+## API vs. webhooks
+
+Depending on your constraints, you may want to use the events API or webhooks. Here is a comparison of the two:
+
+| Aspect         | Events API                                                                | Webhooks                                                                        |
+| -------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Timing         | Controlled by your app. Your server can process events at its own pace.   | Real-time. Webhooks trigger as soon as an event occurs.                         |
+| Order          | A consistent order is guaranteed.                                         | No guarantee of order on receipt. Events contain timestamps to determine order. |
+| Reconciliation | Replayable. Can go back to a specific point in time and reprocess events. | Failed requests are retried with exponential back-off for up to 3 days.         |
+| Security       | Authentication, confidentiality, and integrity protection by default.     | You must expose a public endpoint and validate webhook signatures.              |

package/.docs/organized/docs/events/data-syncing/webhooks.mdx

@@ -0,0 +1,173 @@
+---
+title: Sync data with webhooks
+description: A step-by-step guide on how to start syncing data using webhooks.
+originalPath: .tmp-workos-clone/packages/docs/content/events/data-syncing/webhooks.mdx
+---
+
+## What you’ll build
+
+In this guide, we will walk you through what you will need to set up webhooks:
+
+- Create your endpoint to receive webhook events
+- Register your endpoint with WorkOS
+- Process the events received from WorkOS
+- Test your endpoint
+
+---
+
+## (1) Set up your webhook endpoint
+
+Create a public endpoint that WorkOS can send events to. This endpoint should use HTTPS and should accept POST requests with the `workos-signature` header.
+
+<CodeBlock file="webhook-endpoint">
+  <CodeBlockTab language="js" file="webhook-endpoint-next" title="Next.js" />
+  <CodeBlockTab language="js" file="webhook-endpoint-express" title="Express" />
+  <CodeBlockTab language="ruby" file="webhook-endpoint-rails" title="Rails" />
+  <CodeBlockTab
+    language="ruby"
+    file="webhook-endpoint-sinatra"
+    title="Sinatra"
+  />
+  <CodeBlockTab
+    language="python"
+    file="webhook-endpoint-django"
+    title="Django"
+  />
+  <CodeBlockTab language="python" file="webhook-endpoint-flask" title="Flask" />
+</CodeBlock>
+
+> WorkOS sends the header as `WorkOS-Signature`, but many web servers normalize HTTP request headers to their lowercase variants.
+
+---
+
+## (2) Register your endpoint
+
+Set and save the webhook URL in the [WorkOS Dashboard](https://dashboard.workos.com/), so WorkOS knows where to deliver the events. 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.
+
+![WorkOS Dashboard Webhooks UI](https://images.workoscdn.com/images/a6bebfe6-d5db-475c-bf34-a5bdf35433e0.png?auto=format&fit=clip&q=90)
+
+---
+
+## (3) Process the events
+
+In order to avoid unnecessary retry requests hitting your webhook handler, we recommend using two concurrent processes for handling events: one for receiving the event, and the other for processing it.
+
+### Respond with HTTP 200 OK
+
+On receiving an event, you should respond with an `HTTP 200 OK` to signal to WorkOS that the event was successfully delivered. Otherwise, WorkOS will consider the event delivery a failure and retry up to 12 times, with exponential backoff over 3 days. You do not need to signal to WorkOS whether or not the event was processed successfully.
+
+### (A) Validate the requests using the SDK
+
+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 SDKs provide a method to validate the timestamp and signature of a webhook. Examples using these methods are included below. The parameters are the payload (raw request body), the request header, and the webhook secret.
+
+<CodeBlock title="Webhook validation" file="webhook-validation">
+  <CodeBlockTab language="ruby" file="webhook-validation-rails" title="Rails" />
+  <CodeBlockTab
+    language="ruby"
+    file="webhook-validation-sinatra"
+    title="Sinatra"
+  />
+  <CodeBlockTab
+    language="python"
+    file="webhook-validation-django"
+    title="Django"
+  />
+  <CodeBlockTab
+    language="python"
+    file="webhook-validation-flask"
+    title="Flask"
+  />
+</CodeBlock>
+
+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.
+
+### (B) Validate the requests manually
+
+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` header, delimited by a `,` character.
+
+| Key                | Value                                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `issued_timestamp` | The number of milliseconds since the epoch time at which the event was issued, prefixed by `t=` |
+| `signature_hash`   | The HMAC SHA256 hashed signature for the request, prefixed by `v1=`                             |
+
+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:
+
+1. `issued_timestamp`
+2. The `.` character
+3. The request’s body as a utf-8 decoded string
+
+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 payload in your application’s business logic.
+
+### Create an IP allowlist
+
+WorkOS sends webhooks from a fixed set of IP addresses. It’s recommended to restrict access to your webhook endpoint to only these IP addresses:
+
+```plain title="WorkOS IP addresses"
+3.217.146.166
+23.21.184.92
+34.204.154.149
+44.213.245.178
+44.215.236.82
+50.16.203.9
+52.1.251.34
+52.21.49.187
+174.129.36.47
+```
+
+---
+
+## (4) Test your endpoint
+
+From the dashboard, you can send test webhook events after configuring an endpoint. Go to the webhook endpoint detail page and click the **Send test event** button. The types of events that you have configured for your endpoint are available for you to send sample payloads.
+
+![A screenshot showing how to send a test webhook in the WorkOS dashboard.](https://images.workoscdn.com/images/bda8fdc7-becb-494e-a9b6-f8295e5998a4.png?auto=format&fit=clip&q=90)
+
+If you would like to test against your local development environment, we recommend using a tool like [ngrok](https://ngrok.com) to create a secure tunnel to your local machine, and sending test webhooks to the public endpoint generated with ngrok. See our [blog post](https://workos.com/blog/test-workos-webhooks-locally-ngrok) to get more details on how you may want to test webhooks locally with ngrok.
+
+---
+
+## Best practices
+
+### Respond to events immediately
+
+To avoid webhook requests potentially stressing your system, WorkOS strongly recommends that you respond to a webhook request with a 200 OK response 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 response, and use a background worker to process the messages in the queue.
+
+### Recover from failed events
+
+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](/reference/directory-sync) to update your data.
+
+> In staging environments, WorkOS only retries failed webhooks for several minutes before giving up. You can, however, manually retry webhooks using the WorkOS Dashboard for these environments.
+
+### Handle out-of-sequence events
+
+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:
+
+- `dsync.group.created`
+- `dsync.user.created`
+- `dsync.group.user_added`
+
+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.
+
+### Ignore duplicate events
+
+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.
+
+### Obfuscate your endpoint URL
+
+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.example.com/webhooks/n0dbga5x…` is much more difficult to guess than `https://api.example.com/webhooks`