Create webhook
curl --request POST \
--url https://developer.encrata.com/api/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kind": "<string>",
"events": [
"<string>"
],
"url": "<string>",
"description": "<string>",
"bot_token": "<string>",
"chat_id": "<string>"
}
'import requests
url = "https://developer.encrata.com/api/webhooks"
payload = {
"kind": "<string>",
"events": ["<string>"],
"url": "<string>",
"description": "<string>",
"bot_token": "<string>",
"chat_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
kind: '<string>',
events: ['<string>'],
url: '<string>',
description: '<string>',
bot_token: '<string>',
chat_id: '<string>'
})
};
fetch('https://developer.encrata.com/api/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://developer.encrata.com/api/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'kind' => '<string>',
'events' => [
'<string>'
],
'url' => '<string>',
'description' => '<string>',
'bot_token' => '<string>',
'chat_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://developer.encrata.com/api/webhooks"
payload := strings.NewReader("{\n \"kind\": \"<string>\",\n \"events\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"description\": \"<string>\",\n \"bot_token\": \"<string>\",\n \"chat_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://developer.encrata.com/api/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"kind\": \"<string>\",\n \"events\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"description\": \"<string>\",\n \"bot_token\": \"<string>\",\n \"chat_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://developer.encrata.com/api/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"kind\": \"<string>\",\n \"events\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"description\": \"<string>\",\n \"bot_token\": \"<string>\",\n \"chat_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"result": {
"id": "<string>",
"workspace_id": "<string>",
"kind": "<string>",
"url": "<string>",
"secret": "<string>",
"events": [
"<string>"
],
"is_active": true,
"description": "<string>",
"config": {},
"created_by": {},
"created_at": "<string>",
"updated_at": "<string>"
},
"message": "<string>"
}Webhooks
Create webhook
Register an endpoint to receive workspace events.
POST
/
api
/
webhooks
Create webhook
curl --request POST \
--url https://developer.encrata.com/api/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kind": "<string>",
"events": [
"<string>"
],
"url": "<string>",
"description": "<string>",
"bot_token": "<string>",
"chat_id": "<string>"
}
'import requests
url = "https://developer.encrata.com/api/webhooks"
payload = {
"kind": "<string>",
"events": ["<string>"],
"url": "<string>",
"description": "<string>",
"bot_token": "<string>",
"chat_id": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
kind: '<string>',
events: ['<string>'],
url: '<string>',
description: '<string>',
bot_token: '<string>',
chat_id: '<string>'
})
};
fetch('https://developer.encrata.com/api/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://developer.encrata.com/api/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'kind' => '<string>',
'events' => [
'<string>'
],
'url' => '<string>',
'description' => '<string>',
'bot_token' => '<string>',
'chat_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://developer.encrata.com/api/webhooks"
payload := strings.NewReader("{\n \"kind\": \"<string>\",\n \"events\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"description\": \"<string>\",\n \"bot_token\": \"<string>\",\n \"chat_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://developer.encrata.com/api/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"kind\": \"<string>\",\n \"events\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"description\": \"<string>\",\n \"bot_token\": \"<string>\",\n \"chat_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://developer.encrata.com/api/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"kind\": \"<string>\",\n \"events\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"description\": \"<string>\",\n \"bot_token\": \"<string>\",\n \"chat_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"result": {
"id": "<string>",
"workspace_id": "<string>",
"kind": "<string>",
"url": "<string>",
"secret": "<string>",
"events": [
"<string>"
],
"is_active": true,
"description": "<string>",
"config": {},
"created_by": {},
"created_at": "<string>",
"updated_at": "<string>"
},
"message": "<string>"
}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.Authorization: Bearer enc_xxxxxxxxxxxx
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
generic - a signed HTTP endpoint
generic - a signed HTTP endpoint
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.slack - an incoming webhook
slack - an incoming webhook
Encrata posts
{"text": "..."} to your Slack incoming webhook. The host must be hooks.slack.com.Requires url.discord - a channel webhook
discord - a channel webhook
Encrata posts
{"content": "..."} to your Discord webhook URL.Requires url.telegram - a bot message
telegram - a bot message
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
curl -X POST https://developer.encrata.com/api/webhooks \
-H "Authorization: Bearer enc_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/encrata",
"events": ["lookup.completed", "credits.low"],
"description": "Production webhook"
}'
import requests
response = requests.post(
"https://developer.encrata.com/api/webhooks",
headers={"Authorization": "Bearer enc_xxxxxxxxxxxx"},
json={
"url": "https://example.com/webhooks/encrata",
"events": ["lookup.completed", "credits.low"],
"description": "Production webhook",
},
)
webhook = response.json()["result"]
print(webhook["id"], webhook["secret"])
const response = await fetch("https://developer.encrata.com/api/webhooks", {
method: "POST",
headers: {
Authorization: "Bearer enc_xxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com/webhooks/encrata",
events: ["lookup.completed", "credits.low"],
description: "Production webhook",
}),
});
const { result } = await response.json();
console.log(result.id, result.secret);
curl -X POST https://developer.encrata.com/api/webhooks \
-H "Authorization: Bearer enc_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"kind": "slack",
"url": "https://hooks.slack.com/services/T000/B000/XXXXXXXX",
"events": ["credits.low", "credits.exhausted"],
"description": "#alerts channel"
}'
curl -X POST https://developer.encrata.com/api/webhooks \
-H "Authorization: Bearer enc_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"kind": "telegram",
"bot_token": "123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"chat_id": "-1001234567890",
"events": ["monitor.alert.high_value"]
}'
Response
Returns201 Created.
boolean
true when the webhook was created.object
The created webhook.
Hide webhook
Hide webhook
string
Webhook identifier (UUID).
string
The workspace this webhook belongs to.
string
The destination type you created.
string
The registered URL. Empty for
telegram.string
The HMAC-SHA256 signing secret. Returned for
generic webhooks only. Chat destinations have no signature, so this field is absent for them.string[]
The subscribed event types.
boolean
true for a new webhook. Deliveries begin immediately.string
Your label, trimmed. Empty string when unset.
object
Destination-specific settings. Present only for
telegram, carrying chat_id.string | null
User ID of the creator, or
null when unknown.string
ISO 8601 creation timestamp.
string
ISO 8601 last-updated timestamp.
string
A human-readable summary.
Example response
{
"success": true,
"result": {
"id": "360cb300-d885-4c18-af2c-d259f936bb38",
"workspace_id": "51cdc9d9-203c-4345-b06d-222b560460aa",
"kind": "generic",
"url": "https://example.com/webhooks/encrata",
"secret": "6cce5d5445b12e649ce9e715a2ef4addc9117d6bf3013a0f388997ed20711b1c",
"events": ["lookup.completed", "credits.low"],
"is_active": true,
"description": "Production webhook",
"created_by": "e861d7cb-1d7f-48d9-ab13-9af06a4055cf",
"created_at": "2026-05-02T12:00:00Z",
"updated_at": "2026-05-02T12:00:00Z"
},
"message": "Webhook created."
}
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
| Status | Code | When |
|---|---|---|
400 | bad_request | The JSON body could not be parsed. |
401 | unauthorized | The API key is missing, revoked, or disabled. |
403 | forbidden | Your role is not admin. |
422 | validation_failed | A field failed validation. See the table below. |
500 | internal | Encrata could not create the webhook. Retry. |
Validation messages
message | Cause |
|---|---|
That is not a supported destination type. | kind is not one of the four allowed values. |
A webhook URL is required. | url was empty for a generic destination. |
The webhook URL must use HTTPS. | url did not start with https://. |
The webhook URL is not allowed: ... | The URL resolved to a private, loopback, or otherwise blocked address. |
That does not look like a Slack webhook URL. | kind was slack but the host was not hooks.slack.com. |
A Telegram bot token is required. | kind was telegram without bot_token. |
A Telegram chat ID is required. | kind was telegram without chat_id. |
Select at least one event to subscribe to. | events was empty or missing. |
That is not a valid event type: X. | events contained an unknown event. |
That event is listed twice: X. | events contained a duplicate. |
The description must be 255 characters or fewer. | description was too long. |
Example error
{
"success": false,
"result": { "code": "validation_failed" },
"message": "The webhook URL must use HTTPS."
}
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.
Was this page helpful?