API keys and webhooks

Under Interfaces you create API keys that let your own systems call the integration API, and webhooks through which XICBOT reports events to an address on your side. The page lives at https://app.xicbot.de/schnittstellen, in the Administration group of the menu. The basic concepts of the API are covered in API basics.

Who can see and use the page

The Interfaces menu item appears from the Administration role upwards; Owner includes it. With Read or Edit the item is missing, and the API answers 403 with the code role_too_low. Anyone who opens the page anyway sees only “This needs at least the Administration role.”, without forms or lists. Roles are explained in Team and roles.

Keys and webhooks belong to a feature that only the Custom plan includes. Without it, the page shows the sentence “Your … plan does not include this feature. See Billing for the overview.”, with your plan name in place of the ellipsis, and the Go to billing link instead of the forms; if no plan name is known, the sentence reads “Your plan does not cover this. See Billing for the overview.” Keys and webhooks from before a plan change remain listed below, and the sentence “Existing keys and webhooks stay visible here: keys can be revoked and webhooks deleted. As long as the plan does not include the feature, the API rejects these keys and webhooks receive no deliveries.” is added. Revoke, Deliveries and Delete remain; Send test, Turn off and Turn on are not shown. Through the API, creating, changing and testing answer 402 with plan_feature_missing, and so does every call with such a key; the list, the delivery log, revoking and deleting work without the feature. Once the plan includes the feature again, the same keys and webhooks continue to work; events from the time in between are not delivered later. Which plans include the feature is shown under Pricing and Plans and quotas.

• Only the Owner role can create a key with the Read conversations scope, because that scope returns messages in plain text. For other roles the checkbox is disabled. The API rejects such an attempt with 403, role_too_low and "required": "owner", and the app reports “Only the account owner can do this.”
• Creating a key, creating a webhook and Send test share one limit of 10 calls per minute per signed-in person. Beyond that the API answers 429 and the app shows “Too many attempts. Please wait a moment.”
• If the account is not active, calls from this page return 403 with a code of the form tenant_<status>; the message field reads “Das Konto ist derzeit nicht aktiv.” (the account is currently not active). The app shows “This account is locked. Please write to mail@xicbot.de.”

API keys

An API key starts with xbot_ followed by 48 random characters. “A key is shown in plain text exactly once. Only its fingerprint is stored.” Besides the SHA-256 fingerprint, the first 12 characters are kept as the Identifier. A lost key therefore cannot be recovered, only replaced.

Creating a key

1. 1

   Step 1

   Enter a name

   Under Name enter a label that lets you recognise the key later, for example the system that uses it. At most 80 characters.

2. 2

   Step 2

   Set limit and expiry

   Requests per minute caps how often this key may call per minute and is prefilled with 120. Expires in days sets an expiry date counted from creation; “Empty means no expiry.”

3. 3

   Step 3

   Choose scopes

   Under Scopes tick at least one scope. Without a name or a scope, Create a new key stays disabled.

4. 4

   Step 4

   Copy the key

   The Your new key card appears with the note “Copy it now. After closing it cannot be retrieved again.” Copy key puts it on the clipboard, after which Key copied is shown; if the clipboard cannot be reached, you see The clipboard is not available here. Select the value and copy it manually. Close removes it from view. Name, scopes and expiry are cleared; the limit keeps its value.

Scopes

A key can only call the routes whose scope it carries; “Writing is a separate scope. Without it a key only reads.” GET /api/v1/integration/status needs no scope. Which routes each scope opens and how the API rejects a missing scope is described in API authentication.

What each route returns is described in API integration.

The key list

The list shows the account's keys, newest first. As long as none exists, it reads “No key created yet.”

Revoking a key

Revoke asks for confirmation: “Revoke this key? Requests using it will be rejected from then on.” Only a second Revoke takes effect; Cancel leaves the key unchanged. The key then stays in the list with the status revoked and cannot be made valid again; requests using it get 401 and invalid_key. Expired keys can be revoked as well.

Using a key

Send the key in the X-Api-Key header to routes under /api/v1/integration. A key in the URL, that is ?api_key= or ?key=, is rejected with 400 and key_in_url. Details on authentication are in API authentication, on limits in API limits.

curl -s https://app.xicbot.de/api/v1/integration/status \
  -H "X-Api-Key: $XICBOT_API_KEY"

How the API checks a key step by step, and which response belongs to which step, is described in API authentication; the per-minute and daily caps are in API limits.

Webhooks

A webhook is a target address in your system to which XICBOT sends a signed POST request for the events you select. “Every delivery carries a signature in the X-XICBOT-Signature header. Failed deliveries are retried.” As long as none exists, the section reads “No webhook set up yet.”

Creating a webhook

1. 1

   Step 1

   Enter the target address

   Under Target address enter your receiver's address, for example https://example.com/xicbot-webhook, at most 2048 characters. http and https are accepted; we recommend https. Which targets are rejected is listed under Permitted target addresses.

2. 2

   Step 2

   Choose events

   Under Events tick at least one of the ten events. Without an address or an event, Create webhook stays disabled.

3. 3

   Step 3

   Store the secret

   The Your signing secret card appears with the sentence “Use it to verify the signature of an incoming delivery.” The secret starts with whsec_ followed by 48 characters. Copy secret puts it on the clipboard, Close removes it from view.

Events

Next to the label shown in the app is the technical name that arrives in the event field and the X-XICBOT-Event header. Which fields data carries depends on the event; identifiers arrive as strings.

Capturing the same enquiry or appointment request again does not trigger a second event. Visitor text in question and reason goes out masked: email addresses, phone numbers, account numbers and street addresses appear as placeholders such as [E-Mail]; masking happens before shortening. The plain text of a conversation is only available through a key with the conversations scope, which only the owner can create. There is also the probe event; it only comes from Send test, cannot be subscribed to and carries a note field in data. For conversations, handovers and knowledge see Conversations, Appointments and cases and Knowledge and answers.

Test and deliveries

Each webhook card shows the target address, the subscribed events and the state valid or disabled, followed by Consecutive failures with count and limit, for example 0 / 20.

• Send test immediately delivers a request with the probe event, without retries and even to a disabled webhook. Below it, Test delivered appears with your receiver's status code, or Test failed with the text from the delivery reasons, otherwise with the status code or the connection error message. The page then shows this webhook's deliveries. A test counts towards Consecutive failures like any other delivery.
• Deliveries expands the webhook's last 50 deliveries, newest first, with the columns Time, Events, Attempt, Status and Duration. On success, Status shows the status code; on a failure it shows the text from the delivery reasons, otherwise the status code or the connection error message. Duration is given in milliseconds. With no entries it reads “No delivery yet.”
• For each delivery a SHA-256 hash of the body sent is stored, not the content. Retries of one event appear as separate rows with an increasing Attempt.

Disabling, enabling, deleting

The card's third button toggles the webhook: it reads Turn off for a running webhook and Turn on for a disabled one. A disabled webhook receives no events, and retries already scheduled are dropped. Enabling it resets Consecutive failures to 0.

Delete asks first: Delete this webhook? Deliveries to this address stop immediately, and the signing secret cannot be restored. The target address appears below it, with the buttons Cancel and Delete. Only the confirmation removes the webhook together with its delivery log; pending deliveries are dropped. The address and the secret cannot be changed. The subscribed events can be changed via PUT /api/v1/webhooks/{id}, not in the app.

Delivery and signature

Structure of a delivery

Each delivery is a POST with a JSON body of four fields: event, at (time of the event in ISO 8601, the same for every attempt), tenant (your account's identifier) and data. Non-ASCII characters and slashes are not escaped.

{
  "event": "lead.created",
  "at": "2026-09-28T10:15:00+00:00",
  "tenant": "<account-id>",
  "data": {
    "id": "<enquiry-id>",
    "conversation_id": "<conversation-id>"
  }
}

Verifying the signature

The signature is an HMAC-SHA256 over the timestamp t, a dot and the unmodified request body. The key is the entire secret including whsec_. Verify the raw body as it arrives, not JSON re-encoded from it: a different field order or escaped characters produce a different signature.

• Split the X-XICBOT-Signature header at the commas and read t and v1.
• Compute HMAC-SHA256 with the secret over t, a dot and the raw body, and encode it as hex.
• Compare the result with v1 in constant time, not with a plain equality check.
• Limit the age of the delivery via t, for example to five minutes, so a captured delivery cannot be replayed later.
• Respond within 8 seconds with a status from 200 to 299 and do heavy work afterwards.

import { createHmac, timingSafeEqual } from 'node:crypto';

// Checks X-XICBOT-Signature against the raw body (Buffer or string).
export function verifySignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    String(header ?? '').split(',').map((part) => part.split('=', 2)),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) {
    return false; // missing or too old
  }
  const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const given = Buffer.from(String(parts.v1 ?? ''), 'hex');
  const wanted = Buffer.from(expected, 'hex');
  return given.length === wanted.length && timingSafeEqual(given, wanted);
}

<?php
// Read the raw body, not $_POST and not re-encoded JSON
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_XICBOT_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $parts);
$t = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('XICBOT_WEBHOOK_SECRET'));
$fresh = abs(time() - $t) <= 300;
if (!$fresh || !hash_equals($expected, (string) ($parts['v1'] ?? ''))) {
    http_response_code(400);
    exit;
}
http_response_code(204);
$event = json_decode($body, true);

As a cross-check, the SHA-256 hash of the raw body matches the delivery's content_hash field in GET /api/v1/webhooks/{id}/deliveries.

Retries

Events are delivered in the background. A response with status 200 to 299 within 8 seconds counts as success. Redirects with status 300 to 399 are not followed and count as failures. After a failure, a second attempt follows after about 30 seconds and a third after about 120 seconds; if that fails too, the event is not delivered any further. Background processing is described in Background jobs.

• Every attempt is signed afresh: t changes and X-XICBOT-Attempt goes up. at and X-XICBOT-Delivery stay the same for every attempt of an event, so you can recognise a retry by X-XICBOT-Delivery. A test gets a new identifier each time it is sent.
• If the webhook is disabled or deleted by the time of an attempt, or the plan no longer includes the feature, the delivery is dropped without further attempts and without an entry in the delivery log.
• If the target address check only fails at sending time, for example because the host name now points to an internal address, the attempt is logged, retried and counted towards Consecutive failures just like a receiver that does not respond. If the signing secret cannot be read, the attempt is logged and retried but does not count towards Consecutive failures.

Permitted target addresses

The address is checked on creation and before every send. http and https are accepted. The host name has to resolve to a public address; private and reserved ranges such as 10.0.0.0/8 or 192.168.0.0/16 are rejected. If the host name points to several addresses, each of them has to be public; the connection is made only to the checked addresses. On creation the app reports “This address is not permitted as a target.”, and the API answers 422 with one of the reasons url_unreadable, scheme_not_allowed, name_unresolvable or target_not_allowed in the error field.

Reasons for failed deliveries

These codes appear in the reason field of a test and in the error field of the delivery log. The app shows the following texts for them:

Managing via the API

The same operations are available under /api/v1. Authenticate with the session token of a person holding at least the Administration role, not with an API key: an API key manages neither keys nor webhooks. How to obtain a session token is explained in API authentication. Errors come back as JSON, usually with a code in the error field; field errors are listed in the errors field.

Key endpoints

curl -s https://app.xicbot.de/api/v1/keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ERP sync", "scopes": ["leads", "leads.write"], "limit_per_min": 60, "expires_in_days": 365}'

Webhook endpoints

Error responses

Retention and deletion

• The delivery log is deleted after the log retention period that applies to your account; if it is set to 0, this deletion does not take place. Deleting a webhook deletes its log too.
• Revoked and expired keys remain in the list; individual keys cannot be deleted.
• The account's data export contains keys, webhooks and the delivery log, but without key hashes and without signing secrets.
• When the account is deleted, keys, webhooks and the delivery log are deleted.

Retention periods and the export are covered in Retention and deletion, the protection of credentials in Data security.

Frequent questions