Webhooks
ConnectCloud pushes events to your systems as signed HTTP POST requests, following the Standard Webhooks specification. All outgoing webhooks are sent by the Comms module, so they share one configuration, one retry policy and one delivery log.
Set up outgoing webhooks
You need comms:admin (or do it in the portal: Einstellungen › Benachrichtigungen).
1. Create a webhook channel: where events go.
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/channels' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{
"kind": "webhook",
"name": "Ticket-Sync",
"config": { "format": "json_event" },
"secrets": {
"url": "https://integration.example.com/connectcloud/events",
"signingSecret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
}'
format:json_event(the JSON body below) orteams_card(a Microsoft Teams Adaptive Card, for Teams or Power Automate workflows).urlis stored encrypted (webhook URLs often contain a token) and never returned.signingSecretiswhsec_+ base64 of at least 24 random bytes. Leave it out and a secret is generated for you. Secrets are never returned by the API.- The URL must be a public address (use HTTPS); internal addresses are refused and redirects are not followed.
POST /channels/{id}/testsends acomms.testevent.
2. Decide which events are announced: a flow. Comms has no notification rules of its own (the /rules routes are
gone): what happens when an event occurs is a flow with an event trigger and, to tell people, a
mail node.
schemaVersion: 1
key: kritische-tickets-melden
name: Kritische Tickets melden
triggers:
- { id: neues_ticket, kind: event, event: desk.item.created, filter: "trigger.data.priority in ['hoch', 'kritisch']" }
nodes:
info:
kind: mail
to: ["group:<group id>", "channel:<id of the webhook channel>"]
subject: "Kritisches Ticket {{ trigger.data.number }}"
text: "{{ trigger.data.title ?? '' }}"
edges:
- neues_ticket -> info
- A webhook channel is addressed with
to: ["channel:<id>"]– the id of the channel from step 1 (a Microsoft Teams channel of comms is addressed the same way). Each channel gets one request per run of the node, without recipients; itstypeisflows.message(see "A flow's message" below). - The same
tolist reaches people: employees (person:<e-mail>or the bare address,employee:<id>), groups (group:<id>), roles (role:<id>) and managers (manager:<e-mail or employee id>). A company flow (a tenant flow) also mails addresses outside the company; a personal flow reaches employees only. mandatory: true(people cannot switch the mail off in their notification settings) andmailChannel: <id>(the e-mail channel the people's mail is sent through instead of the default) are reserved for company flows without scope, managed withtenant:flows:admin; in a personal or scoped flow the draft reportsmail_option_not_allowedand is not published.- The events a flow can start on, with their payload schemas, are listed by the flows catalogue
(
GET /catalog); thefilteris an expression overtrigger.data. - People can also subscribe to events for themselves in their own notification settings (personal subscriptions); the
events offered there and their fields are listed by
GET /bootstrapof comms. Examples:desk.item.created,desk.item.transitioned,desk.item.commented,desk.item.handed_off,forge.item.created,forge.item.status_changed,hr.absence.requested,hr.absence.approved,hr.travel.submitted,hr.application.received,hr.interview.confirmed,trade.invoice.issued,dms.document.created.
The request you receive
POST /connectcloud/events HTTP/1.1
Content-Type: application/json
User-Agent: ConnectCloud-Comms/1
webhook-id: 0f6b5c1e-4c33-4d1a-a1a5-2cb8e6f9d0a7
webhook-timestamp: 1772443800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{
"id": "0f6b5c1e-4c33-4d1a-a1a5-2cb8e6f9d0a7",
"eventId": "0f6b5c1e-4c33-4d1a-a1a5-2cb8e6f9d0a7",
"type": "desk.item.created",
"occurredAt": "2026-03-02T09:30:00Z",
"title": "Neues Ticket #1234: VPN-Verbindung bricht ab",
"message": "Anna Schmidt hat ein Ticket angelegt.",
"url": "https://app.mbcom.cloud/desk/tickets/1234",
"facts": [ { "title": "Priorität", "value": "hoch" } ],
"data": {
"itemId": "3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12",
"number": 1234,
"status": "neu",
"title": "VPN-Verbindung bricht ab",
"spaceName": "Support",
"typeName": "Störung",
"assignees": [],
"watchers": [],
"changes": []
}
}
data holds the machine-readable fields of the event; title, message and facts are rendered
for people. Desk item events carry itemId, spaceId, typeId, number, status, actor,
changes ([{field, from, to}]), title, priority, confidential, createdBy, assignees,
watchers, customerName, spaceName, typeName and dueAt. Descriptions and custom field
values are never part of an event: load the item through the API when you need them. Forge item
events (forge.item.created, status_changed, assigned, commented, closed, scm_deployed) carry only
itemId, ref (APP-12), projectKey, typeKey, statusKey, statusCategory, environment and person
references – never the title. The handoff events (desk.item.handed_off, handoff_received,
handed_back, handback_received, converted; forge.item.handoff_received, handback_received,
handoff_notice, converted_from) are item events of the item they happened to. New fields may be added at any
time.
A flow's message
What a flow's mail node posts into a webhook channel (to: ["channel:<id>"]) has the same envelope and the type
flows.message:
{
"id": "5b0d6c0e-2f0a-4d0b-9b1c-0e8f6a7d3c21",
"eventId": "9a1f4c2e-6b7d-4e8f-a0b1-c2d3e4f5a6b7",
"type": "flows.message",
"occurredAt": "2026-03-02T09:30:00Z",
"title": "Kritisches Ticket 1234",
"message": "VPN-Verbindung bricht ab",
"facts": [ { "title": "Flow", "value": "Kritische Tickets melden" } ],
"data": {
"subject": "Kritisches Ticket 1234",
"text": "VPN-Verbindung bricht ab",
"flowName": "Kritische Tickets melden"
}
}
idis the message,eventIdthe run of the flow (every message of one run shares it; read the run withGET /runs/{id}).titleis the node's renderedsubject,messageits renderedtext;factsnames the flow;dataholds the same three values (subject,text,flowName). There is nourland norecipient.- The message carries only what the node's templates render. To pass fields of the event that started the flow, put
them into
subjectortext(e.g. a JSON line intext), or let your endpoint load the record through the API.
Verify the signature
Always verify before you trust a request. The signature is an HMAC-SHA256 over
<webhook-id>.<webhook-timestamp>.<raw body> with the base64-decoded part of the secret after
whsec_. The header holds v1,<base64 signature> (several, space-separated, during secret
rotation). Also reject timestamps older than five minutes to stop replays.
import base64, hashlib, hmac, time
def verify(secret: str, headers: dict, body: bytes, tolerance: int = 300) -> bool:
msg_id, ts, sigs = headers["webhook-id"], headers["webhook-timestamp"], headers["webhook-signature"]
if abs(time.time() - int(ts)) > tolerance:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()).decode()
return any(hmac.compare_digest(expected, s.split(",", 1)[1]) for s in sigs.split() if s.startswith("v1,"))
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(secret: string, h: Record<string, string>, body: Buffer, tolerance = 300): boolean {
const id = h["webhook-id"], ts = h["webhook-timestamp"], sigs = h["webhook-signature"] ?? "";
if (Math.abs(Date.now() / 1000 - Number(ts)) > tolerance) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = createHmac("sha256", key).update(`${id}.${ts}.`).update(body).digest();
return sigs.split(" ").some((s) => {
const [v, sig] = s.split(",");
const got = Buffer.from(sig ?? "", "base64");
return v === "v1" && got.length === expected.length && timingSafeEqual(got, expected);
});
}
func verify(secret string, h http.Header, body []byte) bool {
ts, err := strconv.ParseInt(h.Get("webhook-timestamp"), 10, 64)
if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
return false
}
key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
if err != nil {
return false
}
mac := hmac.New(sha256.New, key)
fmt.Fprintf(mac, "%s.%d.", h.Get("webhook-id"), ts)
mac.Write(body)
expected := mac.Sum(nil)
for _, s := range strings.Fields(h.Get("webhook-signature")) {
if v, sig, ok := strings.Cut(s, ","); ok && v == "v1" {
if got, err := base64.StdEncoding.DecodeString(sig); err == nil && hmac.Equal(got, expected) {
return true
}
}
}
return false
}
Standard Webhooks libraries for many languages verify this for you
(pip install standardwebhooks, npm i standardwebhooks, …).
Answer quickly, process later
- Answer with any
2xxwithin a few seconds, then process asynchronously. webhook-idis unique per delivery: store it and ignore repeats, deliveries are at least once.- Events can arrive out of order. Compare
occurredAt, or load the current state through the API. - Non-
2xxanswers and timeouts are retried with exponential backoff and jitter;Retry-Afteron a429or503is honoured. Redirects (3xx) are not followed and count as failure. A delivery that still fails after its last attempt isdead; fix the endpoint and retry it from the delivery log. - Every attempt is visible in the delivery log:
GET /deliveries, retry one withPOST /deliveries/{id}/retry.
Incoming webhooks
The other direction: let an external system post events into ConnectCloud, for example to start
a workflow. Create an endpoint with POST /inbound-hooks
(comms:admin); the answer contains its public url and, once, its secret.
| Scheme | The sender proves itself with |
|---|---|
standard_webhooks (default) |
the three webhook-* headers as above |
hmac_sha256 |
an HMAC-SHA256 of the body in a header you name (config.signatureHeader, optional prefix like sha256=) |
token |
a static token in a header you name |
The sender posts to POST /api/comms/v1/hooks/{publicId}
without any ConnectCloud token. Verified requests are stored (202), repeats of the same delivery
id answer 200, failed checks 401 without details. Received events are listed with
GET /inbound-hooks/{id}/events.
To start an automation instead of storing the request, give a flow a webhook trigger: it gets its own address
POST /api/flows/v1/hooks/{token} with an optional HMAC signature – see Flows.