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

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.