Bring Your Own Agent (BYOA) lets you connect an external AI agent that you own and host to monday.com. Once connected, the agent has its own monday.com identity, can be @mentioned in updates, assigned to items, and act on boards through the monday.com API.

When triggered, monday.com sends a signed HTTP POST to a callback URL you provide. Your service processes the event and calls back into monday.com using an API token issued at setup time.

🚧

BYOA is in alpha and under active development as of April 2026. Breaking changes are expected before general availability. All BYOA operations require the request header api-version: dev.

Prerequisites

• A monday.com account with AI Agents enabled.
• All API requests must include the header api-version: dev.

Step 1. Create the agent in the Developer Center

1. Navigate to AI Agents → Manage agents and click Bring your agent.
2. Choose Custom agent, enter a name, and provide a Callback URL.

📘

The callback URL is currently required. If you don't have a permanent endpoint yet, use a placeholder HTTPS URL that returns HTTP 200 (for example, a temporary health-check route). Support for an optional callback URL is planned for a future release.

3. Click Create. On the success modal, copy all fields — especially the API Token. These credentials are shown only once and cannot be retrieved again.

Step 2. Connect via the API

You can also create a custom agent programmatically using the connect_external_agent_sync mutation.

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

Variables:

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

Response fields:

❗️

signing_secret and api_token are returned only once and are never shown or logged again. Store them immediately in a secrets manager. If lost, you must disconnect and reconnect the agent.

🚧

connect_external_agent_sync is synchronous and takes approximately 25 seconds. Set your client timeout to at least 40 seconds and show a loading state while waiting.

Step 3. Handle incoming webhook events

When the agent is triggered, monday.com sends a signed POST request to your callback URL.

Request body:

{
  "event": "agent_triggered",
  "triggerType": "mention",
  "payload": {
    "text": "<trigger text>",
    "...": "trigger-specific fields"
  },
  "timestamp": "2026-04-15T10:30:00Z"
}

Request headers:

Limits: 30-second request timeout; response body capped at 1 MB.

Step 4. Verify the webhook signature

Every incoming webhook must be verified before processing. Use constant-time comparison to prevent timing attacks.

1. Read x-monday-signature and x-monday-timestamp from the request headers.
2. Compute HMAC-SHA256(signing_secret, "{x-monday-timestamp}.{raw_body}").
3. Prefix your result with sha256= and compare it to x-monday-signature using a constant-time comparison function.
4. Reject requests where signatures don't match or the timestamp is stale.

const crypto = require('crypto');

function verifySignature(signingSecret, rawBody, headers) {
  const timestamp = headers['x-monday-timestamp'];
  const receivedSig = headers['x-monday-signature'];

  if (!timestamp || !receivedSig) return false;

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

  // timingSafeEqual throws if the buffers differ in length, so guard first —
  // a missing or malformed signature must be rejected, not crash the handler.
  const expectedBuf = Buffer.from(expected);
  const receivedBuf = Buffer.from(receivedSig);
  return (
    expectedBuf.length === receivedBuf.length &&
    crypto.timingSafeEqual(expectedBuf, receivedBuf)
  );
}

🚧

The callback_url must be a valid HTTPS URL reachable from monday.com's infrastructure. It is re-validated at execution time as a protection against SSRF and DNS-rebinding attacks.

Grant board access

Connected agents act under their own monday.com identity — your own account access does not carry over to the agent. You must explicitly grant the agent access to boards or docs it needs to read or modify.

Via the UI: Go to the agent's page → Knowledge and access → add the boards you want the agent to access.

Via the API:

mutation AddAgentToBoard {
  add_agent_resource_access(
    id: "your-agent-id"
    resource_id: "your-board-or-doc-id"
    scope_type: BOARD
    permission_type: READ_WRITE
  ) {
    success
  }
}

Headers required:

api-version: dev

📘

If a board is in a non-default data region, the agent's API token must be able to reach that region.

Use the agent

Once connected and granted access, act as the agent by calling the monday.com GraphQL API using its API token. All actions run under the agent's identity and are subject to its permissions.

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

Disconnect an agent

To disconnect an agent, use the disconnect_external_agent mutation. This revokes the agent's token and deletes the agent from monday.com.

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

Troubleshooting

The agent says it has access but can't edit items. The agent acts under its own identity. Grant READ_WRITE access to the relevant board via add_agent_resource_access — your own board access has no effect on the agent.

Webhook signature verification is failing. Ensure you are computing HMAC-SHA256 over "{x-monday-timestamp}.{raw_body}" using the signing_secret from the connection response (not the API token). Use the raw, unparsed request body.

The secrets were lost after setup. signing_secret and api_token are shown only once. If lost, disconnect the agent with disconnect_external_agent and reconnect to generate new credentials.

The connect_external_agent_sync call is timing out. The mutation is synchronous and takes approximately 25 seconds. Set your HTTP client timeout to at least 40 seconds.

The agent can't create workspaces or perform certain admin actions. Some platform permissions are not yet granted to connected agents in the alpha. This is a known limitation under active development. Report specific blockers to the platform team.

📘

Join our developer community!

If you have questions or need help with BYOA, visit the monday.com developer community.