# Webhooks TypeScript SDK client for the epilot Webhooks: usage with @epilot/sdk, all operations and schemas. - **Base URL:** `https://webhooks.sls.epilot.io` - **Full API Docs:** [https://docs.epilot.io/api/webhooks](https://docs.epilot.io/api/webhooks) ## Usage ```ts import { epilot } from '@epilot/sdk' epilot.authorize(() => '') const { data } = await epilot.webhooks.getPublicKey(...) ``` ### Tree-shakeable import ```ts import { getClient, authorize } from '@epilot/sdk/webhooks' const webhooksClient = getClient() authorize(webhooksClient, () => '') const { data } = await webhooksClient.getPublicKey(...) ``` ## Operations **webhooks** - [`getPublicKey`](#getpublickey) - [`getConfiguredEvents`](#getconfiguredevents) - [`getConfigs`](#getconfigs) - [`createConfig`](#createconfig) - [`getConfig`](#getconfig) - [`updateConfig`](#updateconfig) - [`deleteConfig`](#deleteconfig) - [`triggerWebhook`](#triggerwebhook) - [`batchReplayEvents`](#batchreplayevents) - [`getEventById`](#geteventbyid) - [`replayEvent`](#replayevent) - [`getWebhookExample`](#getwebhookexample) **Events** - [`getWebhookEventsV2`](#getwebhookeventsv2) **Schemas** - [`PublicKeyResponse`](#publickeyresponse) - [`SearchOptions`](#searchoptions) - [`EventListResponse`](#eventlistresponse) - [`HttpMethod`](#httpmethod) - [`AuthType`](#authtype) - [`Filter`](#filter) - [`Auth`](#auth) - [`BasicAuthConfig`](#basicauthconfig) - [`OAuthConfig`](#oauthconfig) - [`ApiKeyConfig`](#apikeyconfig) - [`WebhookConfig`](#webhookconfig) - [`EventConfigResp`](#eventconfigresp) - [`EventConfigEntry`](#eventconfigentry) - [`ErrorResp`](#errorresp) - [`TriggerWebhookResp`](#triggerwebhookresp) - [`PayloadConfiguration`](#payloadconfiguration) - [`CustomHeader`](#customheader) - [`CustomOAuthParameter`](#customoauthparameter) - [`Metadata`](#metadata) - [`ExecutionPayload`](#executionpayload) - [`WebhookEvent`](#webhookevent) - [`ExampleRequest`](#examplerequest) - [`ExampleResponse`](#exampleresponse) - [`BatchReplayRequest`](#batchreplayrequest) ### `getPublicKey` Returns the platform-level Ed25519 public key used to verify asymmetric (v1a) webhook signatures. This endpoint is unauthenticated since the public key is not a secret, but the orgId parameter is requ `GET /v1/webhooks/.well-known/public-key` ```ts const { data } = await client.getPublicKey({ orgId: 'example', }) ```
Response ```json { "public_key": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA...\n-----END PUBLIC KEY-----\n", "algorithm": "ed25519", "issuer": "epilot" } ```
--- ### `getConfiguredEvents` Retrieve events that can trigger webhooks `GET /v1/webhooks/configured-events` ```ts const { data } = await client.getConfiguredEvents() ```
Response ```json [ { "eventName": "customer_request_created", "eventLabel": "Customer Request Created" } ] ```
--- ### `getConfigs` Search Webhook Client Configs `GET /v1/webhooks/configs` ```ts const { data } = await client.getConfigs({ eventName: 'example', }) ```
Response ```json [ { "eventName": "CustomerRequest_Created", "url": "https://my-partner-service.api.com", "httpMethod": "POST", "enabled": true, "auth": { "authType": "BASIC", "basicAuthConfig": { "username": "secretUsername", "password": "secret7825@!" } }, "filter": { "keyToFilter": "customer_request.productId", "supportedValues": ["2324245", "5253642"] } } ] ```
--- ### `createConfig` Create Webhook Client Config `POST /v1/webhooks/configs` ```ts const { data } = await client.createConfig( null, { eventName: 'CustomerRequest_Created', url: 'https://my-partner-service.api.com', httpMethod: 'POST', enabled: true, auth: { authType: 'BASIC', basicAuthConfig: { username: 'secretUsername', password: 'secret7825@!' } }, filter: { keyToFilter: 'customer_request.productId', supportedValues: ['2324245', '5253642'] } }, ) ```
Response ```json { "eventName": "CustomerRequest_Created", "url": "https://my-partner-service.api.com", "httpMethod": "POST", "enabled": true, "auth": { "authType": "BASIC", "basicAuthConfig": { "username": "secretUsername", "password": "secret7825@!" } }, "filter": { "keyToFilter": "customer_request.productId", "supportedValues": ["2324245", "5253642"] } } ```
--- ### `getConfig` Get webhook config by id `GET /v1/webhooks/configs/{configId}` ```ts const { data } = await client.getConfig({ configId: 'example', }) ```
Response ```json { "eventName": "CustomerRequest_Created", "url": "https://my-partner-service.api.com", "httpMethod": "POST", "enabled": true, "auth": { "authType": "BASIC", "basicAuthConfig": { "username": "secretUsername", "password": "secret7825@!" } }, "filter": { "keyToFilter": "customer_request.productId", "supportedValues": ["2324245", "5253642"] } } ```
--- ### `updateConfig` Update Webhook Client Config `PUT /v1/webhooks/configs/{configId}` ```ts const { data } = await client.updateConfig( { configId: 'example', }, { eventName: 'CustomerRequest_Created', url: 'https://my-partner-service.api.com', httpMethod: 'POST', enabled: true, auth: { authType: 'BASIC', basicAuthConfig: { username: 'secretUsername', password: 'secret7825@!' } }, filter: { keyToFilter: 'customer_request.productId', supportedValues: ['2324245', '5253642'] } }, ) ```
Response ```json { "eventName": "CustomerRequest_Created", "url": "https://my-partner-service.api.com", "httpMethod": "POST", "enabled": true, "auth": { "authType": "BASIC", "basicAuthConfig": { "username": "secretUsername", "password": "secret7825@!" } }, "filter": { "keyToFilter": "customer_request.productId", "supportedValues": ["2324245", "5253642"] } } ```
--- ### `deleteConfig` Delete Webhook Client Config `DELETE /v1/webhooks/configs/{configId}` ```ts const { data } = await client.deleteConfig({ configId: 'example', }) ``` --- ### `triggerWebhook` triggers a webhook event either async or sync `POST /v1/webhooks/configs/{configId}/trigger` ```ts const { data } = await client.triggerWebhook( { sync: true, configId: 'example', }, { metadata: { action: 'Manual triggered by user with id 123456', origin: 'string', creation_timestamp: 'string', webhook_id: 'string', webhook_name: 'string', automation_name: 'string', organization_id: 'string', user_id: 'string', correlation_id: 'string', execution_id: 'string', action_id: 'string' } }, ) ```
Response ```json { "status_code": "string", "message": "string", "body": {}, "code": "string", "status": "succeeded", "start_date": "string", "end_date": "string", "event_id": "string" } ```
--- ### `batchReplayEvents` Replay a batch of webhook events `POST /v1/webhooks/configs/{configId}/events/replay-batch` ```ts const { data } = await client.batchReplayEvents( { configId: 'example', }, { eventIds: ['2f1b7cf8-ff55-4359-966f-e56f39a52c94', '48c984bf-466b-470b-b743-d07cea168243'] }, ) ``` --- ### `getEventById` Get a webhook event by its id `GET /v1/webhooks/configs/{configId}/events/{eventId}` ```ts const { data } = await client.getEventById({ configId: 'example', eventId: 'example', }) ```
Response ```json { "event_id": "string", "org_id": "string", "webhook_config_id": "string", "url": "string", "created_at": "2021-04-27T12:01:13.000Z", "event_name": "string", "http_response": { "status_code": 0, "message": "string", "body": {}, "code": "string" }, "metadata": { "action": "Manual triggered by user with id 123456", "origin": "string", "creation_timestamp": "string", "webhook_id": "string", "webhook_name": "string", "automation_name": "string", "organization_id": "string", "user_id": "string", "correlation_id": "string", "execution_id": "string", "action_id": "string" }, "status": "succeeded", "http_method": "GET", "payload": "string" } ```
--- ### `replayEvent` Replay a webhook event `POST /v1/webhooks/configs/{configId}/events/{eventId}/replay` ```ts const { data } = await client.replayEvent({ configId: 'example', eventId: 'example', }) ``` --- ### `getWebhookExample` Generate an example payload for a webhook configuration based on trigger type `POST /v1/webhooks/configs/{configId}/example` ```ts const { data } = await client.getWebhookExample( { configId: 'example', }, { automation_id: 'automation_123' }, ) ```
Response ```json { "metadata": { "action": "Manual triggered by user with id 123456", "origin": "string", "creation_timestamp": "string", "webhook_id": "string", "webhook_name": "string", "automation_name": "string", "organization_id": "string", "user_id": "string", "correlation_id": "string", "execution_id": "string", "action_id": "string" }, "entity": {}, "relations": [ {} ] } ```
--- ### `getWebhookEventsV2` List webhook events and filter them by status, timestamp, etc. `POST /v2/webhooks/configs/{configId}/events` ```ts const { data } = await client.getWebhookEventsV2( { configId: 'example', }, { limit: 25, cursor: { created_at: '2025-10-31T12:34:56Z', event_id: 'evt_1234567890abcdef' }, timestamp: { from: '2025-10-01T00:00:00Z', to: '2025-10-31T23:59:59Z' }, event_id: 'evt_1234567890abcdef', status: 'succeeded' }, ) ```
Response ```json { "data": [ { "event_id": "string", "org_id": "string", "webhook_config_id": "string", "url": "string", "created_at": "2021-04-27T12:01:13.000Z", "event_name": "string", "http_response": { "status_code": 0, "message": "string", "body": {}, "code": "string" }, "metadata": { "action": "Manual triggered by user with id 123456", "origin": "string", "creation_timestamp": "string", "webhook_id": "string", "webhook_name": "string", "automation_name": "string", "organization_id": "string", "user_id": "string", "correlation_id": "string", "execution_id": "string", "action_id": "string" }, "status": "succeeded", "http_method": "GET", "payload": "string" } ], "next_cursor": { "created_at": "2025-10-31T12:34:56Z", "event_id": "evt_1234567890abcdef" }, "has_more": true } ```
--- ## Schemas ### `PublicKeyResponse` ```ts type PublicKeyResponse = { public_key: string algorithm: string issuer?: string } ``` ### `SearchOptions` ```ts type SearchOptions = { limit?: number cursor?: { created_at?: string // date-time event_id?: string } timestamp?: { from?: string // date-time to?: string // date-time } event_id?: string status?: "succeeded" | "failed" } ``` ### `EventListResponse` ```ts type EventListResponse = { data?: Array<{ event_id: string org_id: string webhook_config_id: string url?: string created_at?: string event_name?: string http_response?: { status_code?: { ... } message?: { ... } body?: { ... } code?: { ... } } metadata?: { action?: { ... } origin?: { ... } creation_timestamp?: { ... } webhook_id?: { ... } webhook_name?: { ... } automation_name?: { ... } organization_id: { ... } user_id?: { ... } correlation_id?: { ... } execution_id?: { ... } action_id?: { ... } } status?: "succeeded" | "failed" | "in_progress" http_method?: "GET" | "POST" | "PUT" payload?: string }> next_cursor?: { created_at?: string // date-time event_id?: string } has_more?: boolean } ``` ### `HttpMethod` ```ts type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" ``` ### `AuthType` ```ts type AuthType = "BASIC" | "OAUTH_CLIENT_CREDENTIALS" | "API_KEY" | "NONE" ``` ### `Filter` ```ts type Filter = { keyToFilter: string supportedValues: string[] } ``` ### `Auth` ```ts type Auth = { authType: "BASIC" | "OAUTH_CLIENT_CREDENTIALS" | "API_KEY" | "NONE" basicAuthConfig?: { username: string password?: string passwordIsEnvVar?: boolean } oauthConfig?: { clientId: string clientSecret?: string clientSecretIsEnvVar?: boolean endpoint: string httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" customParameterList?: Array<{ type: { ... } key: { ... } value: { ... } }> } apiKeyConfig?: { keyName: string keyValue?: string keyValueIsEnvVar?: boolean } } ``` ### `BasicAuthConfig` To be sent only if authType is BASIC ```ts type BasicAuthConfig = { username: string password?: string passwordIsEnvVar?: boolean } ``` ### `OAuthConfig` To be sent only if authType is OAUTH_CLIENT_CREDENTIALS ```ts type OAuthConfig = { clientId: string clientSecret?: string clientSecretIsEnvVar?: boolean endpoint: string httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" customParameterList?: Array<{ type: "body" | "query" | "header" key: string value: string }> } ``` ### `ApiKeyConfig` To be sent only if authType is API_KEY ```ts type ApiKeyConfig = { keyName: string keyValue?: string keyValueIsEnvVar?: boolean } ``` ### `WebhookConfig` ```ts type WebhookConfig = { id?: string name: string eventName: string url?: string creationTime?: string httpMethod?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" enabled?: boolean auth?: { authType: "BASIC" | "OAUTH_CLIENT_CREDENTIALS" | "API_KEY" | "NONE" basicAuthConfig?: { username: { ... } password?: { ... } passwordIsEnvVar?: { ... } } oauthConfig?: { clientId: { ... } clientSecret?: { ... } clientSecretIsEnvVar?: { ... } endpoint: { ... } httpMethod: { ... } customParameterList?: { ... } } apiKeyConfig?: { keyName: { ... } keyValue?: { ... } keyValueIsEnvVar?: { ... } } } filter?: { keyToFilter: string supportedValues: string[] } payloadConfiguration?: { hydrate_entity?: boolean include_relations?: boolean include_activity?: boolean include_changed_attributes?: boolean custom_headers?: Record } enableStaticIP?: boolean status?: "active" | "inactive" | "incomplete" jsonataExpression?: string _manifest?: string // uuid[] signingSecret?: string } ``` ### `EventConfigResp` ```ts type EventConfigResp = Array<{ eventName?: string eventLabel?: string }> ``` ### `EventConfigEntry` ```ts type EventConfigEntry = { eventName?: string eventLabel?: string } ``` ### `ErrorResp` ```ts type ErrorResp = { message?: string } ``` ### `TriggerWebhookResp` ```ts type TriggerWebhookResp = { status_code?: string message?: string body?: object code?: string status?: "succeeded" | "failed" start_date?: string end_date?: string event_id: string } ``` ### `PayloadConfiguration` Configuration for the webhook payload ```ts type PayloadConfiguration = { hydrate_entity?: boolean include_relations?: boolean include_activity?: boolean include_changed_attributes?: boolean custom_headers?: Record } ``` ### `CustomHeader` Object representing custom headers as key-value pairs. ```ts type CustomHeader = Record ``` ### `CustomOAuthParameter` Custom key/value pair of either type body, query or header ```ts type CustomOAuthParameter = { type: "body" | "query" | "header" key: string value: string } ``` ### `Metadata` Contains the metadata about the configured event ```ts type Metadata = { action?: string origin?: string creation_timestamp?: string webhook_id?: string webhook_name?: string automation_name?: string organization_id: string user_id?: string correlation_id?: string execution_id?: string action_id?: string } ``` ### `ExecutionPayload` Payload for triggering a webhook ```ts type ExecutionPayload = { metadata: { action?: string origin?: string creation_timestamp?: string webhook_id?: string webhook_name?: string automation_name?: string organization_id: string user_id?: string correlation_id?: string execution_id?: string action_id?: string } } ``` ### `WebhookEvent` ```ts type WebhookEvent = { event_id: string org_id: string webhook_config_id: string url?: string created_at?: string event_name?: string http_response?: { status_code?: number message?: string body?: object code?: string } metadata?: { action?: string origin?: string creation_timestamp?: string webhook_id?: string webhook_name?: string automation_name?: string organization_id: string user_id?: string correlation_id?: string execution_id?: string action_id?: string } status?: "succeeded" | "failed" | "in_progress" http_method?: "GET" | "POST" | "PUT" payload?: string } ``` ### `ExampleRequest` ```ts type ExampleRequest = { automation_id?: string } ``` ### `ExampleResponse` ```ts type ExampleResponse = { metadata?: { action?: string origin?: string creation_timestamp?: string webhook_id?: string webhook_name?: string automation_name?: string organization_id: string user_id?: string correlation_id?: string execution_id?: string action_id?: string } entity?: Record relations?: Record[] } ``` ### `BatchReplayRequest` ```ts type BatchReplayRequest = { eventIds: string[] } ``` ### `Using Webhooks in Blueprints` If webhooks are always reset to their default settings after a blueprint sync, this is because the blueprint overwrites the webhook data. To prevent this, we have introduced environment variables, which remain unchanged during a blueprint sync. Here is how to set them up: 1. Click the gear icon in the top bar to open the environment variables and secrets. 2. Add a variable for your webhook password by entering the key (variable name), the type (String or Secret), and the value. 3. Navigate to "Integrations" and select "Webhooks". 4. Change the authentication setting from "Default" to e.g. "Basic Auth". 5. Enter your username. 6. Click the brackets in the password field — the input will change accordingly. You can now select the relevant environment variable you defined for the password. 7. Save your settings.