Your own systems

On this page

• Custom action
• Approval and value limit
• Custom MCP server
• Connect with sign-in (Notion, Linear, Atlassian)
• Statuspage
• Signed-in customers
• Paldra API

Custom action

Plan: Custom actions and your own MCP servers come with Business – up to 3 actions and MCP tools in total and one MCP server. Enterprise allows up to 10 actions and 5 MCP servers.

What happens: When a question matches the description, the chatbot calls your system and phrases the answer only from what your system returns. Also works with Make and n8n (webhook with response).

Edit and test

Below each action you find Edit (loads it into the form; the key and token secret stay if you leave the fields empty) and Test now: you enter sample values, Paldra really calls your system and shows the status, duration and the start of the response. For POST the page asks first – your system will then really carry out the action. Headers and keys are never shown.

Security & limits

Per action (for MCP per server) under Security & limits:

• Verified customers only (on by default, also for existing actions): in chat, WhatsApp and Instagram the chatbot asks for the email address and sends a 6-digit code (valid for 10 minutes, at most 5 attempts). Signed-in customers are already verified. In emails only a technically verified sender address (DMARC/DKIM) counts; otherwise the chatbot looks nothing up and a team member takes over the action. Code emails are also limited per address, per requester and per shop. Only then does the action run – even one that only reads. Your system receives the verified address in X-Alpheris-Customer-Email (signed for custom actions).
• At most per conversation (default 3) and per day (default 200, counted over 24 hours). When a limit is reached, the chatbot honestly tells the customer that it can't look it up right now.
• Turn off after failures in a row (default 5): if your system answers with an error that many times in a row, Paldra turns the action off. The dashboard then shows a notice with the last error and Turn back on; saving the action turns it back on as well.
• Channels: chat, email, WhatsApp and Instagram (all by default). In other channels the chatbot does not offer the action.

Approval, value limit and what the customer hears

Below every action that changes data (custom action with POST, MCP tool that does more than read) you find Approval:

• Value limit: “If field > value, then Draft or Agent”. Below the limit, the level you set for the action applies (e.g. AI replies). You can pick fields of type Number or Whole number. A value that is not a number counts as above. The limit only raises the level, never lowers it. Shopify refunds keep their own amount limit from the Shopify rules.
• Who may approve: everyone with the “Approve actions” team permission (owners and admins always) or only specific people. API keys and connected apps can never approve.

Approving in chat, WhatsApp and Instagram: if the AI prepared an action in the conversation, Approve in the inbox carries it out. The result is then shown on the action (Done, or Failed with the reason), and the customer gets a short message in the same channel: “Done: … has been carried out.” or “That didn't work: … Our team is looking into it and will get back to you.” When you reject, Paldra sends nothing – tell the customer why yourself.

For developers: verifying calls, long-running jobs, API

Every custom action in the dashboard has a For developers button: signing secret, shop ID, callback address and a ready-made brief to copy – for your developer or for Claude Code (“connect this Paldra action to our system”). This is how you connect your own SaaS, e.g. “create a business plan for the customer”.

Verify calls (HMAC)

Every call carries X-Alpheris-Timestamp, X-Alpheris-Request-Id and X-Alpheris-Signature: v1=…; for verified customers also X-Alpheris-Customer-Email (signed in, confirmed by code, or a technically verified email sender). The signature is HMAC-SHA256(secret, "<timestamp>.<request_id>.<customer_email>.<body>") – <body> is the raw JSON for POST and the query string without “?” for GET. Reject calls whose timestamp is more than 5 minutes off.

import hmac, hashlib, time

def alpheris_ok(geheimnis: str, kopf: dict, body: bytes) -> bool:
    ts = kopf.get("X-Alpheris-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    basis = f"{ts}.{kopf.get('X-Alpheris-Request-Id', '')}.{kopf.get('X-Alpheris-Customer-Email', '')}.".encode() + body
    soll = "v1=" + hmac.new(geheimnis.encode(), basis, hashlib.sha256).hexdigest()
    return hmac.compare_digest(soll, kopf.get("X-Alpheris-Signature", ""))

const crypto = require("crypto");
function alpherisOk(geheimnis, h, rawBody) {
  const ts = h["x-alpheris-timestamp"] || "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const basis = `${ts}.${h["x-alpheris-request-id"] || ""}.${h["x-alpheris-customer-email"] || ""}.` + rawBody;
  const soll = "v1=" + crypto.createHmac("sha256", geheimnis).update(basis).digest("hex");
  const ist = h["x-alpheris-signature"] || "";
  return soll.length === ist.length && crypto.timingSafeEqual(Buffer.from(soll), Buffer.from(ist));
}

Sign-in with a token (OAuth, login)

If your system needs a token first, enter the token address, key and secret under “Sign-in with a token” in the form – Paldra fetches the token itself, keeps it until shortly before it expires and fetches a new one once on 401. Two types: OAuth 2 client credentials (e.g. Haufe axera link: the provider’s token address, client ID, client secret) and JSON login (e.g. casavi: POST …/v2/authenticate with your provider’s field names, token field token, header token without prefix; facilioo: login with API key). The secret is stored encrypted and never shown.

Sign-in via OAuth (“Connect with X”)

If your system is accessed through a sign-in page (OAuth 2 authorization code), set it up below the list of your custom actions under “Set up sign-in”: authorization URL, token URL, client ID, client secret, scopes and optionally the revocation URL. Enter the redirect URL shown, https://app.alpheris.com/integrations/oauth/callback, at the provider and tap “Connect with provider”. Paldra uses PKCE (S256), stores the access encrypted, sends it as Authorization: Bearer …, renews it before it expires and once after a 401. The sign-in is kept when you edit the action.

Long-running jobs

If your system needs more than 8 seconds (e.g. to create a document), reply right away with 202 and {"auftrag_id": "…", "hinweis": "Takes about 2 minutes."}. The chatbot tells the customer it is running. When the result is ready, report it signed (same secret, its own timestamp and request id) to https://api.alpheris.com/public/aktionen/rueckmeldung with the header X-Alpheris-Shop. The result appears in the customer’s chat. status: fertig (done), fehler (failed) or laeuft (progress, at most three).

curl -X POST https://api.alpheris.com/public/aktionen/rueckmeldung \
  -H "Content-Type: application/json" \
  -H "X-Alpheris-Shop: 148" -H "X-Alpheris-Timestamp: $TS" -H "X-Alpheris-Request-Id: $ID" \
  -H "X-Alpheris-Signature: v1=$SIG" \
  -d '{"auftrag_id":"bp-77","status":"fertig","text":"Dein Businessplan ist fertig.","link":"https://dein-system.de/p/77"}'

Create actions via API

With an API key your developer (or Claude Code) creates actions directly: GET/POST /v1/aktionen, DELETE /v1/aktionen/{domain}. Same fields and checks as in the dashboard (plus optional grenzen, e.g. {"je_gespraech": 3, "je_tag": 200, "aus_nach": 5, "kanaele": ["chat", "mail"]}); on first creation the signing secret is returned once (geheimnis). Details in the API reference.

curl -X POST "$ALPHERIS_BASE_URL/v1/aktionen" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Businessplan erstellen", "beschreibung": "Wenn ein Kunde einen Businessplan möchte",
       "url": "https://dein-system.de/alpheris/businessplan", "methode": "POST", "stufe": "kunde",
       "parameter": [{"name": "Branche", "typ": "auswahl", "werte": ["Café", "Handwerk"], "pflicht": true},
                     {"name": "Budget", "typ": "zahl"}],
       "antwort_felder": ["status", "plan.titel"]}'

Custom MCP server

What happens: When a question matches a tool, the chatbot calls it and answers from the result - like Fin with MCP connectors. Up to five servers with Enterprise, one with Business – there you choose per tool with “Use” which one takes one of the 3 slots. Security & limits work as for the custom action (per server, counted per tool); the verified address is sent in the X-Alpheris-Customer-Email header.

Connect with sign-in (Notion, Linear, Atlassian)

Notion, Linear and Atlassian (Jira, Confluence) offer their own MCP servers with sign-in. You need no key and no developer app: you sign in with the provider and allow Paldra access.

Your own MCP server with sign-in: if your server requires a sign-in (response 401 with WWW-Authenticate), just enter the address and tap “Connect with sign-in”. Paldra reads the server’s sign-in details (OAuth Protected Resource Metadata, Authorization Server Metadata), registers itself as an app (Dynamic Client Registration) and opens the sign-in. If your server offers no automatic app registration, connect it with an access token.

What Paldra stores: the access encrypted, the granted permissions and the expiry. Paldra renews the access itself shortly before it expires. If the provider rejects the renewal, the tile shows “Sign-in expired”, you get an email, and the chatbot only uses the tools again after “Reconnect”. When you disconnect, Paldra revokes the access with the provider where supported.

Redirect URL (for custom actions with sign-in): https://app.alpheris.com/integrations/oauth/callback

Statuspage

What happens: When someone asks about an outage (“Is checkout down?”), the chatbot answers with the open incidents and maintenance on your status page - or that everything is running normally.

Workflows

What happens: When the event occurs and the conditions match, Paldra sends it to the target within seconds – each event exactly once. An address receives the same JSON body as webhooks, signed with the workflow’s secret (in the dashboard under “Secret”); a custom action receives {"ereignis", "workflow", "daten"}, signed with its own secret and the header X-Alpheris-Event. Each workflow shows when it last ran and whether it worked.

Signed-in customers

What happens: If the signature matches, the email is marked as verified in the conversation. The chatbot then shares order status and open invoices without asking, as long as the email matches the order or invoice; custom actions and MCP tools run without a code. Without a valid signature nothing changes.

Paldra API

What happens: Your system reads and writes conversations, tickets and leads. Details are in the API reference.

Custom action: PUT, PATCH, DELETE, headers, body template, GraphQL

Under “More: headers, body template, GraphQL” in the custom action form (or via /v1/aktionen) you can do more than GET and POST:

• Methods: GET and DELETE send the details in the URL, POST, PUT and PATCH as JSON. PUT and PATCH start at least at the draft stage; the AI never runs DELETE on its own – only after “customer confirms”, as a draft or by a team member.
• Additional headers: up to 8, values stored encrypted (e.g. CF-Access-Client-Id and CF-Access-Client-Secret for Cloudflare Access). Not allowed: Host, Content-Length, Content-Type and any X-Alpheris-….
• Body template: valid JSON with placeholders {{detail}} in quotes, nested as deep as you like. If a placeholder stands alone in the string, the value keeps its type (a number stays a number); if an optional detail is missing, the key is left out.
• GraphQL: POST with query and a variables template. A query only reads, a mutation is an action with a stage. If the server answers with errors only, the call counts as failed.

{
  "customer": { "email": "{{email}}", "name": "{{name}}" },
  "items": [ { "sku": "{{item}}", "quantity": "{{quantity}}" } ],
  "note": "Ordered in chat: {{item}}"
}

The OpenAPI import now also reads YAML (openapi.yaml) and suggests actions for GET, POST, PUT, PATCH and DELETE. Signature, address check, 8-second timeout and “no redirects” apply to all methods alike; the body is limited to 100 KB.

If your system is not on the public internet (inventory, property management, ERP in the company network), read Connect internal systems.

Lookup tables

For knowledge that lives in a table: delivery zones by postcode, opening hours per branch, spare part numbers, maintenance contracts, units and contacts. The AI looks things up in it – read only, never writes.

What happens: When a customer asks something that is in a table, the AI fetches at most five matching rows and phrases the answer only from them. With the customer check, only a securely identified customer gets anything – in chat signed in via signed-in customers, by email via their sender address if its authenticity is verified via DKIM/DMARC – and only rows with their own email address. An address typed into the chat is never enough.