Skip to main content
POST
Create webhook
Registers a destination for one or more workspace events. Encrata starts delivering as soon as the webhook is created.

Authentication

Send your API key as a bearer token.
Creating a webhook requires the workspace admin role. tech and readonly keys get 403.

Request

string
default:"generic"
Destination type. One of generic, slack, discord, or telegram. The kind is fixed at creation and cannot be changed later.
string[]
required
Event types to subscribe to. Must contain at least one event, every value must be a known event, and duplicates are rejected.Valid values: lookup.completed, bulk.completed, apikey.created, apikey.revoked, credits.low, credits.exhausted, monitor.run.completed, monitor.alert.high_value.
string
required
The HTTPS URL that receives deliveries. Required for generic, slack, and discord. Omit it for telegram.The URL must use https:// and must resolve to a public address. Private, loopback, and link-local addresses are rejected.
string
A label for the webhook. Trimmed, and limited to 255 characters.
string
Telegram bot token. Required when kind is telegram, ignored otherwise.
string
Telegram chat ID to post into. Required when kind is telegram, ignored otherwise.

Destination rules

The default. Your server receives the raw {event, data, created_at} JSON envelope with an X-Encrata-Signature header. This is the only kind that returns a signing secret and the only kind you can verify.Requires url.
Encrata posts {"text": "..."} to your Slack incoming webhook. The host must be hooks.slack.com.Requires url.
Encrata posts {"content": "..."} to your Discord webhook URL.Requires url.
Encrata calls the Telegram Bot API directly. There is no URL to supply: the target is derived from your bot token and chat ID.Requires bot_token and chat_id.
Chat destinations receive a short human-readable message, not the JSON envelope, and they are not signed. Use generic when your application needs to process event data.

Examples

Response

Returns 201 Created.
boolean
true when the webhook was created.
object
The created webhook.
string
A human-readable summary.
Example response
Store the secret when you create the webhook. A workspace admin can read it again with GET /api/webhooks/{id}, but it is never returned by list webhooks.

Errors

Validation messages

Example error

Next steps

Send a test event

Confirm your endpoint is reachable before you rely on it.

Verify signatures

Validate X-Encrata-Signature on every delivery.

Update a webhook

Change events, URL, or pause deliveries.

Inspect deliveries

Debug failures with recent attempts.