Skip to main content

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

Events

Schemas

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

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"
    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[]
}

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
  status?: "active" | "inactive" | "incomplete"
  jsonataExpression?: string
  _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"
  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[]
}