Webhook endpoints let WorkOS deliver event notifications directly to your application. Use these endpoints to create, list, and delete the webhook endpoints configured for your environment.
For implementation guidance, including payload verification and local testing, see the webhooks guide.
Get a list of all of your existing webhook endpoints.
cURL
| curl "https://api.workos.com/webhook_endpoints" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.webhooks.list_webhook_endpoints |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.webhooks.list_webhook_endpoints() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Webhooks().ListEndpoints(context.Background()) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->webhooks()->listWebhookEndpoints(); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.webhooks.listWebhookEndpoints(); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Webhooks.ListEndpointsAsync(); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .webhooks() | |
| .list_webhook_endpoints() | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "object": "webhook_endpoint", | |
| "id": "we_0123456789", | |
| "endpoint_url": "https://example.com/webhooks", | |
| "secret": "whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4", | |
| "status": "enabled", | |
| "events": [ | |
| "user.created", | |
| "dsync.user.created" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } | |
| ], | |
| "list_metadata": { | |
| "before": "we_01HXYZ123456789ABCDEFGHIJ", | |
| "after": "we_01HXYZ987654321KJIHGFEDCBA" | |
| } | |
| } |
GET/webhook_endpoints
Parameters
Returns object
Create a new webhook endpoint to receive event notifications.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/webhook_endpoints" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "endpoint_url": "https://example.com/webhooks", | |
| "events": [ | |
| "user.created", | |
| "dsync.user.created" | |
| ] | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.webhooks.create_webhook_endpoint( | |
| endpoint_url: "https://example.com/webhooks", | |
| events: ["user.created", "dsync.user.created"] | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.webhooks.create_webhook_endpoint( | |
| endpoint_url="https://example.com/webhooks", | |
| events=["user.created", "dsync.user.created"], | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Webhooks().CreateEndpoint(context.Background(), &workos.WebhooksCreateEndpointParams{ | |
| EndpointURL: "https://example.com/webhooks", | |
| Events: []any{"user.created", "dsync.user.created"}, | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->webhooks() | |
| ->createWebhookEndpoint( | |
| endpointUrl: "https://example.com/webhooks", | |
| events: ["user.created", "dsync.user.created"], | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.webhooks.WebhooksApi.CreateWebhookEndpointOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreateWebhookEndpointOptions options = | |
| CreateWebhookEndpointOptions.builder() | |
| .endpointUrl("https://example.com/webhooks") | |
| .events(List.of("user.created", "dsync.user.created")) | |
| .build(); | |
| workos.webhooks.createWebhookEndpoint(options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Webhooks.CreateEndpointAsync(new WebhooksCreateEndpointOptions { | |
| EndpointUrl = "https://example.com/webhooks", | |
| Events = new[] { "user.created", "dsync.user.created" }, | |
| }); |
| use workos::Client; | |
| use workos::webhooks::CreateWebhookEndpointParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .webhooks() | |
| .create_webhook_endpoint( | |
| CreateWebhookEndpointParams { | |
| endpoint_url: "https://example.com/webhooks".into(), | |
| events: vec!["user.created".into(), "dsync.user.created".into()], | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "webhook_endpoint", | |
| "id": "we_0123456789", | |
| "endpoint_url": "https://example.com/webhooks", | |
| "secret": "whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4", | |
| "status": "enabled", | |
| "events": [ | |
| "user.created", | |
| "dsync.user.created" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST/webhook_endpoints
Returns
Update the properties of an existing webhook endpoint.
cURL
| curl --request PATCH \ | |
| --url "https://api.workos.com/webhook_endpoints/we_0123456789" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "endpoint_url": "https://example.com/webhooks", | |
| "status": "enabled", | |
| "events": [ | |
| "user.created", | |
| "dsync.user.created" | |
| ] | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.webhooks.update_webhook_endpoint(id: "we_0123456789") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.webhooks.update_webhook_endpoint(id_="we_0123456789") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Webhooks().UpdateEndpoint(context.Background(), "we_0123456789") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->webhooks()->updateWebhookEndpoint(id: "we_0123456789"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.webhooks.updateWebhookEndpoint("we_0123456789"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Webhooks.UpdateEndpointAsync("we_0123456789"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .webhooks() | |
| .update_webhook_endpoint("we_0123456789") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "webhook_endpoint", | |
| "id": "we_0123456789", | |
| "endpoint_url": "https://example.com/webhooks", | |
| "secret": "whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4", | |
| "status": "enabled", | |
| "events": [ | |
| "user.created", | |
| "dsync.user.created" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
PATCH/webhook_endpoints
Parameters
Returns
Delete an existing webhook endpoint.
cURL
| curl --request DELETE \ | |
| --url "https://api.workos.com/webhook_endpoints/we_0123456789" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.webhooks.delete_webhook_endpoint(id: "we_0123456789") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.webhooks.delete_webhook_endpoint(id_="we_0123456789") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Webhooks().DeleteEndpoint(context.Background(), "we_0123456789") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->webhooks()->deleteWebhookEndpoint(id: "we_0123456789"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.webhooks.deleteWebhookEndpoint("we_0123456789"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Webhooks.DeleteEndpointAsync("we_0123456789"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .webhooks() | |
| .delete_webhook_endpoint("we_0123456789") | |
| .await?; | |
| Ok(()) | |
| } |
DELETE/webhook_endpoints
Parameters
Returns
Group Continue to the next section
Up next