Webhooks

Base URL: https://webhooks.sls.epilot.io
Full API Docs: https://docs.epilot.io/api/webhooks

Usage

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.webhooks.getPublicKey(...)

Tree-shakeable import

import { getClient, authorize } from '@epilot/sdk/webhooks'

const webhooksClient = getClient()
authorize(webhooksClient, () => '<token>')
const { data } = await webhooksClient.getPublicKey(...)

Operations

webhooks

getPublicKey
getConfiguredEvents
getConfigs
createConfig
getConfig
updateConfig
deleteConfig
triggerWebhook
batchReplayEvents
getEventById
replayEvent
getWebhookExample

Events

getWebhookEventsV2

Schemas

PublicKeyResponse
SearchOptions
EventListResponse
HttpMethod
AuthType
Filter
WebhookCondition
WebhookConditionGroup
Auth
BasicAuthConfig
OAuthConfig
ApiKeyConfig
WebhookConfig
EventConfigResp
EventConfigEntry
ErrorResp
TriggerWebhookResp
PayloadConfiguration
CustomHeader
CustomOAuthParameter
Metadata
ExecutionPayload
WebhookEvent
ExampleRequest
ExampleResponse
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

const { data } = await client.getPublicKey({
  orgId: 'example',
})

Response

{
  "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

const { data } = await client.getConfiguredEvents()

Response

[
  {
    "eventName": "customer_request_created",
    "eventLabel": "Customer Request Created"
  }
]

`getConfigs`

Search Webhook Client Configs

GET /v1/webhooks/configs

const { data } = await client.getConfigs({
  eventName: 'example',
})

Response

[
  {
    "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

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

{
  "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}

const { data } = await client.getConfig({
  configId: 'example',
})

Response

{
  "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}

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

{
  "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}

const { data } = await client.deleteConfig({
  configId: 'example',
})

`triggerWebhook`

triggers a webhook event either async or sync

POST /v1/webhooks/configs/{configId}/trigger

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

{
  "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

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}

const { data } = await client.getEventById({
  configId: 'example',
  eventId: 'example',
})

Response

{
  "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

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

const { data } = await client.getWebhookExample(
  {
    configId: 'example',
  },
  {
    automation_id: 'automation_123'
  },
)

Response

{
  "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

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

{
  "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`

type PublicKeyResponse = {
  public_key: string
  algorithm: string
  issuer?: string
}

`SearchOptions`

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" | "skipped"
}

`EventListResponse`

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" | "skipped"
    http_method?: "GET" | "POST" | "PUT"
    payload?: string
  }>
  next_cursor?: {
    created_at?: string // date-time
    event_id?: string
  }
  has_more?: boolean
}

`HttpMethod`

type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD"

`AuthType`

type AuthType = "BASIC" | "OAUTH_CLIENT_CREDENTIALS" | "API_KEY" | "NONE"

`Filter`

type Filter = {
  keyToFilter: string
  supportedValues: string[]
}

`WebhookCondition`

A condition that must be met for the webhook to fire.

type WebhookCondition = {
  field: string
  operation: "equals" | "not_equals" | "any_of" | "none_of" | "contains" | "not_contains" | "starts_with" | "ends_with" | "greater_than" | "less_than" | "greater_than_or_equals" | "less_than_or_equals" | "is_empty" | "is_not_empty"
  values?: string[]
  field_type?: "string" | "number" | "boolean" | "date" | "datetime"
  is_array_field?: boolean
  repeatable_item_op?: boolean
}

`WebhookConditionGroup`

A group of conditions with a logical operator. Multiple conditions are AND-ed by default.

type WebhookConditionGroup = {
  conditions?: Array<{
    field: string
    operation: "equals" | "not_equals" | "any_of" | "none_of" | "contains" | "not_contains" | "starts_with" | "ends_with" | "greater_than" | "less_than" | "greater_than_or_equals" | "less_than_or_equals" | "is_empty" | "is_not_empty"
    values?: string[]
    field_type?: "string" | "number" | "boolean" | "date" | "datetime"
    is_array_field?: boolean
    repeatable_item_op?: boolean
  }>
  logical_operator?: "AND" | "OR"
}

`Auth`

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

type BasicAuthConfig = {
  username: string
  password?: string
  passwordIsEnvVar?: boolean
}

`OAuthConfig`

To be sent only if authType is OAUTH_CLIENT_CREDENTIALS

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

type ApiKeyConfig = {
  keyName: string
  keyValue?: string
  keyValueIsEnvVar?: boolean
}

`WebhookConfig`

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<string, string>
  }
  enableStaticIP?: boolean
  protected?: boolean
  secureProxy?: {
    integration_id: string // uuid
    use_case_slug: string
  }
  status?: "active" | "inactive" | "incomplete"
  jsonataExpression?: string
  filterConditions?: {
    conditions?: Array<{
      field: { ... }
      operation: { ... }
      values?: { ... }
      field_type?: { ... }
      is_array_field?: { ... }
      repeatable_item_op?: { ... }
    }>
    logical_operator?: "AND" | "OR"
  }
  _manifest?: string // uuid[]
  signingSecret?: string
}

`EventConfigResp`

type EventConfigResp = Array<{
  eventName?: string
  eventLabel?: string
}>

`EventConfigEntry`

type EventConfigEntry = {
  eventName?: string
  eventLabel?: string
}

`ErrorResp`

type ErrorResp = {
  message?: string
}

`TriggerWebhookResp`

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

type PayloadConfiguration = {
  hydrate_entity?: boolean
  include_relations?: boolean
  include_activity?: boolean
  include_changed_attributes?: boolean
  custom_headers?: Record<string, string>
}

`CustomHeader`

Object representing custom headers as key-value pairs.

type CustomHeader = Record<string, string>

`CustomOAuthParameter`

Custom key/value pair of either type body, query or header

type CustomOAuthParameter = {
  type: "body" | "query" | "header"
  key: string
  value: string
}

`Metadata`

Contains the metadata about the configured event

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

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`

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" | "skipped"
  http_method?: "GET" | "POST" | "PUT"
  payload?: string
}

`ExampleRequest`

type ExampleRequest = {
  automation_id?: string
}

`ExampleResponse`

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<string, unknown>
  relations?: Record<string, unknown>[]
}

`BatchReplayRequest`

type BatchReplayRequest = {
  eventIds: string[]
}

FilesExpand file tree

webhooks.md

Latest commit

History

webhooks.md

File metadata and controls

Webhooks

Usage

Tree-shakeable import

Operations

getPublicKey

getConfiguredEvents

getConfigs

createConfig

getConfig

updateConfig

deleteConfig

triggerWebhook

batchReplayEvents

getEventById

replayEvent

getWebhookExample

getWebhookEventsV2

Schemas

PublicKeyResponse

SearchOptions

EventListResponse

HttpMethod

AuthType

Filter

WebhookCondition

WebhookConditionGroup

Auth

BasicAuthConfig

OAuthConfig

ApiKeyConfig

WebhookConfig

EventConfigResp

EventConfigEntry

ErrorResp

TriggerWebhookResp

PayloadConfiguration

CustomHeader

CustomOAuthParameter

Metadata

ExecutionPayload

WebhookEvent

ExampleRequest

ExampleResponse

BatchReplayRequest

`getPublicKey`

`getConfiguredEvents`

`getConfigs`

`createConfig`

`getConfig`

`updateConfig`

`deleteConfig`

`triggerWebhook`

`batchReplayEvents`

`getEventById`

`replayEvent`

`getWebhookExample`

`getWebhookEventsV2`

`PublicKeyResponse`

`SearchOptions`

`EventListResponse`

`HttpMethod`

`AuthType`

`Filter`

`WebhookCondition`

`WebhookConditionGroup`

`Auth`

`BasicAuthConfig`

`OAuthConfig`

`ApiKeyConfig`

`WebhookConfig`

`EventConfigResp`

`EventConfigEntry`

`ErrorResp`

`TriggerWebhookResp`

`PayloadConfiguration`

`CustomHeader`

`CustomOAuthParameter`

`Metadata`

`ExecutionPayload`

`WebhookEvent`

`ExampleRequest`

`ExampleResponse`

`BatchReplayRequest`