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 "https://api.workos.com/webhook_endpoints" \ --header "Authorization: Bearer sk_example_123456789"
{ "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" } }
| 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_endpointsParameters Returns objectCreate a new webhook endpoint to receive event notifications.
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
{ "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" }
| 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_endpointsReturns Update the properties of an existing webhook endpoint.
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
{ "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" }
| 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_endpointsParameters Returns Delete an existing webhook endpoint.
curl --request DELETE \ --url "https://api.workos.com/webhook_endpoints/we_0123456789" \ --header "Authorization: Bearer sk_example_123456789"
| 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_endpointsParameters Returns