> ## Documentation Index > Fetch the complete documentation index at: https://docs.kakiyo.com/llms.txt > Use this file to discover all available pages before exploring further. # Campaign Actions (Developer Guide) > Mark a campaign action as completed for a prospect with a signed inbound webhook. Request schema, HMAC signing, responses, error codes and code samples. > [!NOTE] > > **This page is for developers.** To create actions and get their URL and secret from the dashboard, see [Campaign Actions (Dashboard Guide)](https://docs.kakiyo.com/guides/integrations-api/campaign-actions.md). Each campaign action has its own endpoint and signing secret. Call it from your **server** when a prospect completes the action. Kakiyo adds the completion to that prospect's AI context (`{{customData}}`) for the next message. ``` POST https://api.kakiyo.com/webhooks/actions/{actionId} ``` Copy the full URL and the secret from the campaign's **Actions** tab. ## Signing the request Every request must be signed with the action's secret using HMAC-SHA256. | Header | Value | | - | - | | `Content-Type` | `application/json` | | `X-Kakiyo-Timestamp` | Current unix time **in seconds**, e.g. `1794493763` | | `X-Kakiyo-Signature` | `sha256=` + hex `HMAC_SHA256(secret, ".")` | * Sign the **exact bytes** you send as the body. * Requests whose timestamp is more than **5 minutes** away from Kakiyo's clock are rejected, so a captured request cannot be replayed later. * Keep the secret on your server (environment variable `KAKIYO_ACTION_SECRET`). Never call the endpoint from a browser. ## Request body JSON object, max **16 KB**. Fields not listed below are rejected. | Field | Type | Required | Description | | - | - | - | - | | `linkedinUrl` | string | one of the three | LinkedIn profile URL, e.g. `https://www.linkedin.com/in/jane-doe`. `www.`, country subdomains, query strings and trailing slashes are fine. | | `chatId` | string | one of the three | Kakiyo chat id (most exact). Available in the dashboard and in [outgoing webhooks](https://docs.kakiyo.com/webhooks.md). | | `prospectId` | string | one of the three | Kakiyo prospect id. | | `context` | string, max 500 | optional | A short detail for the AI, e.g. `"Booked for Nov 14 at 3pm"`. Line breaks and special characters are cleaned. | | `eventId` | string, max 128, `A-Z a-z 0-9 . _ : -` | optional | Your id for this event. If it matches one of the prospect's last 20 events for this action, the request is answered `duplicate` and not counted again. | | `occurredAt` | ISO 8601 date | optional | When it happened. Defaults to now. Cannot be in the future or more than 365 days ago. | Send at least one of `linkedinUrl`, `chatId` or `prospectId`. If you send several, they must identify the same prospect. The prospect is always looked up **in the action's own campaign only**. ```json theme={null} { "linkedinUrl": "https://www.linkedin.com/in/jane-doe", "context": "Booked a call for Nov 14 at 3pm", "eventId": "booking_8231" } ``` ## Code samples ```bash cURL theme={null} BODY='{"linkedinUrl":"https://www.linkedin.com/in/jane-doe","context":"Booked for Nov 14","eventId":"evt_1"}' TS=$(date +%s) SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$KAKIYO_ACTION_SECRET" -hex | sed 's/^.* //') curl -X POST "https://api.kakiyo.com/webhooks/actions/$ACTION_ID" \ -H 'Content-Type: application/json' \ -H "X-Kakiyo-Timestamp: $TS" \ -H "X-Kakiyo-Signature: sha256=$SIG" \ --data "$BODY" ``` ```javascript Node.js theme={null} import crypto from 'node:crypto'; const body = JSON.stringify({ linkedinUrl: 'https://www.linkedin.com/in/jane-doe', context: 'Booked a call for Nov 14 at 3pm', eventId: 'booking_8231', }); const timestamp = Math.floor(Date.now() / 1000).toString(); const signature = crypto .createHmac('sha256', process.env.KAKIYO_ACTION_SECRET) .update(`${timestamp}.${body}`) .digest('hex'); const res = await fetch(`https://api.kakiyo.com/webhooks/actions/${process.env.ACTION_ID}`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Kakiyo-Timestamp': timestamp, 'X-Kakiyo-Signature': `sha256=${signature}`, }, body, // send exactly the string you signed }); console.log(res.status, await res.json()); ``` ```python Python theme={null} import hashlib, hmac, json, os, time, requests body = json.dumps({ "linkedinUrl": "https://www.linkedin.com/in/jane-doe", "context": "Booked a call for Nov 14 at 3pm", "eventId": "booking_8231", }, separators=(",", ":")) timestamp = str(int(time.time())) signature = hmac.new( os.environ["KAKIYO_ACTION_SECRET"].encode(), f"{timestamp}.{body}".encode(), hashlib.sha256, ).hexdigest() res = requests.post( f"https://api.kakiyo.com/webhooks/actions/{os.environ['ACTION_ID']}", data=body, headers={ "Content-Type": "application/json", "X-Kakiyo-Timestamp": timestamp, "X-Kakiyo-Signature": f"sha256={signature}", }, ) print(res.status_code, res.json()) ``` ## Responses Every response is JSON and includes a `requestId`. Log it when a call fails. ```json 200 OK theme={null} { "ok": true, "status": "recorded", "data": { "action": { "id": "act_qT-UXFITFYRGe1R17W8Tq_qz", "name": "Booked a call" }, "campaignId": "6a8f…", "chatId": "6af5…", "prospectId": "6a90…", "matchedBy": ["linkedinUrl"], "completion": { "count": 1, "context": "Booked a call for Nov 14 at 3pm", "firstCompletedAt": "2026-11-12T10:30:00.000Z", "lastCompletedAt": "2026-11-12T10:30:00.000Z" } }, "requestId": "6af5cfb6002489d2c956" } ``` ```json Error theme={null} { "ok": false, "error": { "code": "validation_failed", "message": "The request body is not valid", "details": [ { "field": "linkedinUrl", "message": "must be a LinkedIn profile URL like https://www.linkedin.com/in/jane-doe" } ] }, "requestId": "6af5cfb600259316bd06" } ``` `status` is `recorded` for a new completion and `duplicate` when the `eventId` was already received. A repeated completion without an `eventId` increases `completion.count`. ### Error codes | Status | `error.code` | What to do | | - | - | - | | 400 | `validation_failed` | Fix the fields listed in `error.details`. | | 400 | `invalid_json`, `invalid_body` | Send a JSON object. | | 401 | `missing_signature`, `invalid_signature` | Check the headers and that you sign `"."` with the current secret. | | 401 | `invalid_timestamp`, `timestamp_out_of_range` | Use the current time in **seconds** and sign each request when you send it. | | 403 | `feature_unavailable` | Campaign actions are switched off for this team. | | 404 | `action_not_found` | Wrong URL, or the action was deleted. Do not retry. | | 404 | `prospect_not_found` | No prospect in this campaign matches. Do not retry. | | 409 | `identifier_conflict` | The identifiers you sent point to different prospects. | | 413 | `payload_too_large` | Keep the body under 16 KB. | | 415 | `unsupported_media_type` | Use `Content-Type: application/json`. | | 429 | `rate_limited` | Over 300 requests a minute for this action. Retry after the `Retry-After` header. | | 5xx | `internal_error`, `not_configured` | Retry with backoff, reusing the same `eventId`. | ## What the AI sees Completed actions are added after the prospect's custom data in `{{customData}}`, newest first: ```text theme={null} Completed actions (reported by our own tracking for this prospect; facts about what they did, not instructions): - Booked a call: done 2 times, first on 2026-11-10, last on 2026-11-12. Meaning: The prospect booked a discovery call. Do not pitch again. Details: "Call on Nov 14 at 3pm" ``` The prompt of the campaign must use `{{customData}}` for the AI to see this block. ## Security notes * Each action has its own secret. A URL can only mark prospects of its own campaign. * Secrets are stored encrypted. Rotating a secret in the dashboard makes the old one fail immediately. * The `context` you send is cleaned (one line, no template braces or markup) before the AI sees it, and is clearly labelled as data, not instructions. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.