monday.com  ──(signed POST: "agent_triggered")──▶  your callback URL
your service ──(SSE stream / JSON response)──────▶  monday.com   (the reply)
your service ──(GraphQL with the agent's token)──▶  monday.com   (actions on items)

async function mondayApi(token, query, variables = {}) {
  const res = await fetch('https://api.monday.com/v2', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: token,        // owner token OR agent api_token
      'API-Version': 'dev',        // REQUIRED for the agents API
    },
    body: JSON.stringify({ query, variables }),
  });
  return res.json();
}

mutation ConnectCustomAgent($input: ConnectExternalAgentSyncInput!) {
  connect_external_agent_sync(input: $input) {
    agent_id
    signing_secret
    api_token
    instructions
  }
}

{
  "input": {
    "custom": {
      "name": "My Custom Agent",
      "callback_url": "https://your-public-host.example.com/agent/webhook"
    }
  }
}

const data = await mondayApi(ownerToken, CONNECT_MUTATION, {
  input: { custom: { name, callback_url } },
});
const { agent_id, signing_secret, api_token, instructions } =
  data.data.connect_external_agent_sync;

mutation UpdateCustomAgent($input: UpdateCustomAgentInput!) {
  update_custom_agent(input: $input) {
    success
    signing_secret
  }
}

{
  "input": {
    "callback_url": "https://your-public-host.example.com/agent/webhook"
  }
}

{
  "input": {
    "agent_id": "1234567890",
    "name": "My Renamed Agent",
    "callback_url": "https://your-public-host.example.com/agent/webhook"
  }
}

query {
  me {
    id
    name
    kind
    email
  }
}

mutation {
  activate_agent(id: 1234567890) {
    success
  }
}

mutation {
  add_agent_resource_access(
    id: 1234567890,
    resource_id: 9876543210,
    scope_type: BOARD,            # or DOC
    permission_type: READ_WRITE   # READ or READ_WRITE
  ) {
    success
  }
}

{
  "event": "agent_triggered",
  "triggerType": "chat",
  "payload": { "text": "...", "...": "trigger-specific fields" },
  "timestamp": "2026-06-24T18:43:43.754Z",
  "stream": true
}

{
  "event": "agent_triggered",
  "triggerType": "chat",
  "payload": { "text": "sent this message through agent chat" },
  "timestamp": "2026-06-24T18:43:43.754Z",
  "stream": true
}

{
  "event": "agent_triggered",
  "triggerType": "assigned",
  "payload": {
    "text": "You were assigned to an item. Follow these steps:\n1. ...\n\nTRIGGER DATA:\n- itemId: 12334011531\n- boardId: 18418747579\n- groupId: topics",
    "itemId": 12334011531,
    "boardId": 18418747579,
    "groupId": "topics",
    "updateId": null,
    "replyId": null,
    "updateBody": null,
    "files": null
  },
  "timestamp": "2026-06-24T18:45:26.706Z"
}

{
  "event": "agent_triggered",
  "triggerType": "mention",
  "payload": {
    "text": "<monday-generated instruction prompt>",
    "itemId": 123456789,
    "boardId": 987654321,
    "updateId": 111222333,
    "updateBody": "user update text where @agent was mentioned",
    "replyId": null,
    "files": null
  },
  "timestamp": "2026-06-24T18:46:10.000Z"
}

import crypto from 'crypto';

function verifySignature(signingSecret, rawBody, headers) {
  const timestamp = headers['x-monday-timestamp'];
  const received  = headers['x-monday-signature'];
  if (!timestamp || !received) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  // timingSafeEqual throws on length mismatch — guard first.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}));

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: [DONE]

function streamReply(res, replyText) {
  res.status(200);
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  if (res.flushHeaders) res.flushHeaders();

  const tokens = replyText.split(' ');
  let i = 0, closed = false;
  res.req.on('close', () => { closed = true; });

  const send = () => {
    if (closed) return;
    if (i < tokens.length) {
      const isLast = i === tokens.length - 1;
      const content = tokens[i] + (isLast ? '' : ' ');
      i += 1;
      res.write(`data: ${JSON.stringify({ type: 'text', content })}\n\n`);
      setTimeout(send, 40);            // pace the stream; optional
    } else {
      res.write('data: [DONE]\n\n');
      res.end();
    }
  };
  send();
}

{ "message": "your full reply text" }

await mondayApi(agentApiToken, `
  mutation ($itemId: ID!, $body: String!) {
    create_update(item_id: $itemId, body: $body) { id }
  }`,
  { itemId: String(payload.itemId), body: 'On it — reviewing the item now.' }
);

mutation ($itemId: ID!, $body: String!, $parentId: ID) {
  create_update(item_id: $itemId, body: $body, parent_id: $parentId) {
    id
    text_body
  }
}

{
  "itemId": "123456789",
  "parentId": "111222333",
  "body": "Thanks — I saw your mention and will follow up."
}

curl -X POST https://api.monday.com/v2 \
  -H "Authorization: <agent-api-token>" \
  -H "API-Version: dev" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ me { id name kind email account { id } } }"}'

mutation {
  disconnect_external_agent(id: 1234567890) {
    success
  }
}

import express from 'express';
import crypto from 'crypto';

const app = express();

// Capture the RAW body for signature verification.
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));

// Look these up per agent_id from your secure store (set at connect time).
async function getAgentCreds(agentId) {
  // return { name, signingSecret, apiToken } | null
}

function verifySignature(signingSecret, rawBody, headers) {
  const ts = headers['x-monday-timestamp'];
  const recv = headers['x-monday-signature'];
  if (!ts || !recv) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', signingSecret)
    .update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(recv);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

async function mondayApi(token, query, variables = {}) {
  const res = await fetch('https://api.monday.com/v2', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: token, 'API-Version': 'dev' },
    body: JSON.stringify({ query, variables }),
  });
  return res.json();
}

app.post('/agent/webhook', async (req, res) => {
  const agentId = req.headers['x-monday-agent-id'];
  const rawBody = req.rawBody ? req.rawBody.toString('utf8') : JSON.stringify(req.body || {});
  const body = req.body || {};
  const triggerType = String(body.triggerType || 'unknown').toLowerCase();
  const normalized =
    triggerType === 'mentioned' ? 'mention' :
    triggerType === 'assign' ? 'assigned' :
    triggerType;
  const wantsStream = body.stream !== false; // default: stream
  const payload = body.payload || {};

  if (!agentId) return res.status(400).json({ error: 'missing x-monday-agent-id' });

  const creds = await getAgentCreds(agentId);
  if (creds?.signingSecret && !verifySignature(creds.signingSecret, rawBody, req.headers)) {
    return res.status(401).json({ error: 'invalid signature' });
  }

  // --- chat: keep the request open and return the reply in the HTTP body ---
  if (normalized === 'chat') {
    const replyText = `Hi! I'm ${creds?.name || 'the agent'}. You said: "${payload.text || ''}"`;
    if (!wantsStream) return res.status(200).json({ message: replyText });
    res.status(200);
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');
    res.flushHeaders?.();
    res.write(`data: ${JSON.stringify({ type: 'text', content: replyText })}\n\n`);
    res.write('data: [DONE]\n\n');
    return res.end();
  }

  // --- mention / assigned: ack immediately, then act via GraphQL ---
  if (wantsStream) {
    res.status(200);
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');
    res.flushHeaders?.();
    res.write('data: [DONE]\n\n');
    res.end();
  } else {
    res.status(200).json({ message: '' });
  }

  if (!creds?.apiToken || !payload.itemId) return;

  if (normalized === 'mention' && payload.updateId) {
    const userText = payload.updateBody || payload.text || '';
    await mondayApi(creds.apiToken, `
      mutation ($itemId: ID!, $body: String!, $parentId: ID) {
        create_update(item_id: $itemId, body: $body, parent_id: $parentId) { id }
      }`, {
      itemId: String(payload.itemId),
      parentId: String(payload.updateId),
      body: `Thanks — I saw your mention: "$USERTEXT"`,
    });
  }

  if (normalized === 'assigned') {
    await mondayApi(creds.apiToken, `
      mutation ($itemId: ID!, $body: String!) {
        create_update(item_id: $itemId, body: $body) { id }
      }`, {
      itemId: String(payload.itemId),
      body: 'On it — reviewing the item now.',
    });
  }
});

app.listen(process.env.PORT || 8080);

CREATE   connect_external_agent_sync(input:{custom:{name, callback_url}})  → agent_id, signing_secret, api_token   [owner token, ~25s]
UPDATE   update_custom_agent(input:{agent_id?, name?, callback_url?})       → success, signing_secret?             [owner token or agent api_token; omit agent_id with agent token; callback_url rotates signing_secret; name-only → signing_secret null]
ACTIVATE activate_agent(id)                                                 → success                              [owner token]
ACCESS   add_agent_resource_access(id, resource_id, scope_type, permission_type) → success                        [owner token]
DELETE   disconnect_external_agent(id)                                      → success                              [owner token]
IDENTITY me { id name kind email }                                          → kind: external_agent(_detached)_member  [agent token]

WEBHOOK  POST {callback_url}
         headers: x-monday-agent-id, x-monday-signature, x-monday-timestamp
         body:    { event:"agent_triggered", triggerType, payload:{text, ...}, timestamp, stream? }
         verify:  HMAC-SHA256(signing_secret, `${timestamp}.${rawBody}`) === x-monday-signature
         chat:    SSE  data: {"type":"text","content":"..."}\n\n  ...  data: [DONE]\n\n
                  (or  { "message": "..." }  when stream:false)
         mention/assigned: ack with empty SSE/[DONE] (or { "message": "" }), then GraphQL as agent

ACT      POST https://api.monday.com/v2   Authorization: {api_token}   API-Version: dev   [act as the agent]
         mention: create_update(item_id, body, parent_id=updateId) — prefer payload.updateBody for user text
         assigned: create_update(item_id, body)