Routine webhooks

A webhook starts a routine when another service (Zapier, Make, n8n, a script, your own server) sends a signed request to its address. The request’s JSON body is passed to the routine along with its prompt, as data. The request gets an answer right away; the run happens afterward, and its result lands in the routine’s conversation.

Create a trigger#Link to the Create a trigger section

1. Open the routine in “Routines”, then the “Webhooks” tab.
2. Click “Create a webhook trigger”. The “Name” is optional: it helps you tell your triggers apart, for example “Zapier new leads”.
3. Copy the “Webhook URL” and the “Signing key”.
4. Click “I saved the key”.

“Show a call example” displays a ready-to-copy command with your address and key.

Each routine can have up to 5 triggers. The “Webhooks” tab shows how many calls each trigger accepts per minute and per day: the daily number depends on the workspace plan (see the plans).

Endpoint reference#Link to the Endpoint reference section

POST /api/v1/routines/hooks/{id}#Link to the POST /api/v1/routines/hooks/{id} section

Starts a run of the routine linked to the trigger.

Parameters#Link to the Parameters section

Response#Link to the Response section

An accepted request returns 202 before the routine runs:

{"run_id": "4b0c1f0e-2a7d-4c41-9e3b-6f1d2c8a5b90", "status": "queued"}

The run appears in the routine’s “History” tab with the “Webhook” trigger. Keep the sending machine’s clock accurate.

The signature#Link to the The signature section

The signature is an HMAC-SHA256:

• the key is the signing key, exactly as shown (it starts with mwk_);
• the message is the timestamp, a period, then the raw body, exactly the bytes sent;
• the result is written in lowercase hexadecimal, 64 characters.

<X-Moon-Timestamp>.<raw body>

To check your computation, use these sample values:

The X-Moon-Signature header can hold up to 5 signatures separated by commas (v1=…,v1=…): the request is accepted if one of them matches. A signature without the v1= prefix is accepted too.

Examples#Link to the Examples section

Replace the address and the key with your trigger’s.

KEY='mwk_your_key'
URL='https://chat.realmoon.ai/api/v1/routines/hooks/your_id'
BODY='{"event":"new_lead","id":"evt_123"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$KEY" -hex | sed 's/^.* //')
curl -sS -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H "X-Moon-Timestamp: $TS" \
  -H "X-Moon-Signature: v1=$SIG" \
  --data-binary "$BODY"

import hashlib, hmac, json, time, requests

key = "mwk_your_key"
url = "https://chat.realmoon.ai/api/v1/routines/hooks/your_id"
body = json.dumps({"event": "new_lead", "id": "evt_123"}).encode()
ts = str(int(time.time()))
sig = hmac.new(key.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()

r = requests.post(url, data=body, headers={
    "Content-Type": "application/json",
    "X-Moon-Timestamp": ts,
    "X-Moon-Signature": f"v1={sig}",
})
print(r.status_code, r.json())

import { createHmac } from 'node:crypto';

const key = 'mwk_your_key';
const url = 'https://chat.realmoon.ai/api/v1/routines/hooks/your_id';
const body = JSON.stringify({ event: 'new_lead', id: 'evt_123' });
const ts = Math.floor(Date.now() / 1000).toString();
const sig = createHmac('sha256', key).update(`${ts}.${body}`).digest('hex');

const res = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Moon-Timestamp': ts,
    'X-Moon-Signature': `v1=${sig}`
  },
  body
});
console.log(res.status, await res.json());

In Python, pass the already encoded body in data= (not json=), so the signed bytes are what gets sent. The JavaScript example runs on Node.js 18 or later.

In Zapier, Make or n8n, use a code step or an HTTP request step that computes the signature on the exact body, then sends it with both headers.

Errors#Link to the Errors section

An error body has the form {"detail": …}. The detail is either a text or a {"code": …, "message": …} object. The texts are returned in French; their meaning is given in parentheses.

Sample bodies:

{"detail": "Introuvable."}

{"detail": {"code": "rate_limited", "message": "Limite de ce déclencheur atteinte."}}

The same 404 is returned for every cause listed, so that nothing reveals whether a trigger exists. Check the address, the key and the signature computation first.

Resend a request#Link to the Resend a request section

• A request refused with 429, 403 or 503 does not count toward the trigger’s limits. You can resend it as is while its timestamp is less than 5 minutes old, or sign it again with a recent time.
• Two identical requests (same body, same second) have the same signature: the second one gets 409. Add a unique event ID to the body, for example "id": "evt_123".
• An accepted request is never run twice, even if it is resent.

What the routine does#Link to the What the routine does section

The routine receives its prompt, followed by the request body presented as data sent by an outside service. The AI uses it as material for the task, without following any instructions it might contain. The body goes through Moon Blur like the rest of the request.

A run started by a webhook:

• never acts in your connectors (no email sent, no message posted), even if the routine has the “Allow actions” option;
• does not open web pages, run code, or generate images or videos;
• does not create a public link to your files or attach any to a message;
• can read your connectors and search the web;
• is not retried automatically after an error;
• counts toward your usage limit like a regular run.

The prompt and the answer are marked as containing outside content: nothing remote loads in the answer until you click. As long as this message stays in the conversation, the following turns keep the same precautions: every action in your tools needs your approval.

Manage triggers#Link to the Manage triggers section

Disabling a trigger, renewing its key or deleting it also cancels its queued runs that have not started yet. The list shows, for each trigger, the “Calls received” and the date of the last call. Deleting the routine deletes its triggers.

See also#Link to the See also section

• Routines
• Messaging apps and triggers