Skip to content

Start building

Jump toWebhook endpoints
All endpoints

Webhook endpoints

Where MyDeepAgents sends signed events: endpoints, secrets, test events and every delivery.

get/v1/webhook_endpoints

List webhook endpoints

Needs webhook.manage

Newest first. Sorts by created_at, updated_at and url; q searches addresses and descriptions, or finds a pasted whe_… ID. Filters, each repeatable: state (active, paused, disabled, pending), workspace_id, created_by, updated_by.

Query parameters

  • statestring[]
  • workspace_idstring[]
  • created_bystring[]
  • updated_bystring[]
  • limitinteger

    Rows per page, 1 to 200.

    Default50at least 1at most 200
  • cursorstring
  • qstring

    Search: rows whose name (or the list's other searchable text) contains this, any case.

    at most 200 characters
  • orderstring

    Sort field; a leading - sorts down. Each list names the fields it sorts by.

    at most 64 charactersmatches ^-?[a-z_]+$
  • includestring[]

    total_count (counted up to 10,000) and facets (a count per filter value).

    One oftotal_countfacets
  • created_afterstring

    Only rows created at or after this time (RFC 3339).

    date-time
  • created_beforestring

    Only rows created at or before this time (RFC 3339).

    date-time
  • updated_afterstring

    Only rows last changed at or after this time (RFC 3339).

    date-time
  • updated_beforestring

    Only rows last changed at or before this time (RFC 3339).

    date-time

Response200

  • objectstring
    list
  • dataWebhookEndpoint[]
    19 fields
    • idstring
    • objectstring
      webhook_endpoint
    • consecutive_failuresinteger
    • created_atstring or null
    • descriptionstring or null
    • disabled_reasonstring or null
      One offailinggone
    • enabledboolean
    • event_typesstring[]
    • failing_sincestring or null
    • last_failure_atstring or null
    • last_success_atstring or null
    • previous_secret_expires_atstring or null
    • row_versioninteger
    • statestring
      One ofpendingactivepauseddisabled
    • updated_atstring or null
    • urlstring
    • workspace_idstring or null
    • created_byActorRef or null

      Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

      5 fields
      • idstring or null
      • kindstring
        One ofuserapi_keyservice_accountworkloadend_usersystem
      • namestring or null
      • avatar_versionstring or null
      • emailstring or null
    • updated_byActorRef or null

      Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

      5 fields
      • idstring or null
      • kindstring
        One ofuserapi_keyservice_accountworkloadend_usersystem
      • namestring or null
      • avatar_versionstring or null
      • emailstring or null
  • has_moreboolean
  • next_cursorstring or null
  • facetsmap<string, map<string, integer>> or null
  • peoplemap<string, ActorRef> or null
    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • total_countinteger or null
  • total_count_exactboolean or null

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl "https://api.mydeepagents.com/v1/webhook_endpoints?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "object": "list",
  "data": [
    {
      "id": "id",
      "object": "webhook_endpoint",
      "consecutive_failures": 2,
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "description": "Reads new support email and drafts a reply.",
      "disabled_reason": null,
      "enabled": true,
      "event_types": [
        "event type"
      ],
      "failing_since": "failing since",
      "last_failure_at": "2026-11-10T09:30:00.000Z",
      "last_success_at": "2026-11-10T09:30:00.000Z",
      "previous_secret_expires_at": "2026-11-10T09:30:00.000Z",
      "row_version": 4,
      "state": "pending",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "url": "https://mcp.example.com/mcp",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}
post/v1/webhook_endpoints

Create webhook endpoint

Needs webhook.manage

Adds an endpoint, active at once, and answers its signing secret — shown this once. Nothing is sent to it until an event it subscribed to happens; send a ping with POST …/test to check it. At most limits.webhook_endpoints (10) per organization.

Request bodyWebhookEndpointCreate

  • event_typesstring[]Required
    at least 1 itemsat most 100 items
  • urlstringRequired
    at least 8 charactersat most 2048 characters
  • descriptionstring or null
    at most 500 characters
  • workspace_idstring or null

Response201

  • idstring
  • objectstring
    webhook_endpoint
  • consecutive_failuresinteger
  • created_atstring or null
  • descriptionstring or null
  • disabled_reasonstring or null
    One offailinggone
  • enabledboolean
  • event_typesstring[]
  • failing_sincestring or null
  • last_failure_atstring or null
  • last_success_atstring or null
  • previous_secret_expires_atstring or null
  • row_versioninteger
  • secretstring
  • statestring
    One ofpendingactivepauseddisabled
  • updated_atstring or null
  • urlstring
  • workspace_idstring or null
  • created_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • updated_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null

Status codes

  • 201Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X POST "https://api.mydeepagents.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Reads new support email and drafts a reply.",
    "event_types": [
      "event type"
    ],
    "url": "https://mcp.example.com/mcp",
    "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
  }'
Response · 201
JSON
{
  "id": "id",
  "object": "webhook_endpoint",
  "consecutive_failures": 2,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "description": "Reads new support email and drafts a reply.",
  "disabled_reason": null,
  "enabled": true,
  "event_types": [
    "event type"
  ],
  "failing_since": "failing since",
  "last_failure_at": "2026-11-10T09:30:00.000Z",
  "last_success_at": "2026-11-10T09:30:00.000Z",
  "previous_secret_expires_at": "2026-11-10T09:30:00.000Z",
  "row_version": 4,
  "secret": "secret",
  "state": "pending",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "url": "https://mcp.example.com/mcp",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}
get/v1/webhook_endpoints/event_types

List webhook event types

Needs webhook.manage

Every event type an endpoint may subscribe to: the domain events marked for webhooks. Each arrives as a thin event (IDs and states); an endpoint may also name {object}.* or *. Test events have the type ping.

Response200

  • objectstring
    list
  • dataWebhookEndpointEventType[]
    2 fields
    • objectstring
    • typestring
  • has_moreboolean
  • next_cursorstring or null
  • facetsmap<string, map<string, integer>> or null
  • peoplemap<string, ActorRef> or null
    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • total_countinteger or null
  • total_count_exactboolean or null

Status codes

  • 200Successful Response
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl "https://api.mydeepagents.com/v1/webhook_endpoints/event_types" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "object": "list",
  "data": [
    {
      "object": "object",
      "type": "type"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}
get/v1/webhook_endpoints/{webhook_endpoint_id}

Get webhook endpoint

Needs webhook.manage

Path parameters

  • webhook_endpoint_idstringRequired

Response200

  • idstring
  • objectstring
    webhook_endpoint
  • consecutive_failuresinteger
  • created_atstring or null
  • descriptionstring or null
  • disabled_reasonstring or null
    One offailinggone
  • enabledboolean
  • event_typesstring[]
  • failing_sincestring or null
  • last_failure_atstring or null
  • last_success_atstring or null
  • previous_secret_expires_atstring or null
  • row_versioninteger
  • statestring
    One ofpendingactivepauseddisabled
  • updated_atstring or null
  • urlstring
  • workspace_idstring or null
  • created_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • updated_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "id": "id",
  "object": "webhook_endpoint",
  "consecutive_failures": 2,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "description": "Reads new support email and drafts a reply.",
  "disabled_reason": null,
  "enabled": true,
  "event_types": [
    "event type"
  ],
  "failing_since": "failing since",
  "last_failure_at": "2026-11-10T09:30:00.000Z",
  "last_success_at": "2026-11-10T09:30:00.000Z",
  "previous_secret_expires_at": "2026-11-10T09:30:00.000Z",
  "row_version": 4,
  "state": "pending",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "url": "https://mcp.example.com/mcp",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}
patch/v1/webhook_endpoints/{webhook_endpoint_id}

Update webhook endpoint

Needs webhook.manage

Changes are saved first. enabled: false turns the endpoint off and abandons the deliveries waiting for it; enabled: true then sends a test event and turns it on only after a 2xx — otherwise 422 (ping_failed), with the other changes kept.

Path parameters

  • webhook_endpoint_idstringRequired

Request bodyWebhookEndpointPatch

  • descriptionstring or null
    at most 500 characters
  • enabledboolean or null
  • event_typesstring[] or null
    at least 1 itemsat most 100 items
  • row_versioninteger or null
  • urlstring or null
    at least 8 charactersat most 2048 characters

Response200

  • idstring
  • objectstring
    webhook_endpoint
  • consecutive_failuresinteger
  • created_atstring or null
  • descriptionstring or null
  • disabled_reasonstring or null
    One offailinggone
  • enabledboolean
  • event_typesstring[]
  • failing_sincestring or null
  • last_failure_atstring or null
  • last_success_atstring or null
  • previous_secret_expires_atstring or null
  • row_versioninteger
  • statestring
    One ofpendingactivepauseddisabled
  • updated_atstring or null
  • urlstring
  • workspace_idstring or null
  • created_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • updated_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X PATCH "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Reads new support email and drafts a reply.",
    "enabled": true,
    "event_types": [
      "event type"
    ],
    "row_version": 4,
    "url": "https://mcp.example.com/mcp"
  }'
Response · 200
JSON
{
  "id": "id",
  "object": "webhook_endpoint",
  "consecutive_failures": 2,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "description": "Reads new support email and drafts a reply.",
  "disabled_reason": null,
  "enabled": true,
  "event_types": [
    "event type"
  ],
  "failing_since": "failing since",
  "last_failure_at": "2026-11-10T09:30:00.000Z",
  "last_success_at": "2026-11-10T09:30:00.000Z",
  "previous_secret_expires_at": "2026-11-10T09:30:00.000Z",
  "row_version": 4,
  "state": "pending",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "url": "https://mcp.example.com/mcp",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}
delete/v1/webhook_endpoints/{webhook_endpoint_id}

Delete webhook endpoint

Needs webhook.manage

Removes it: nothing more is sent, waiting deliveries stop, its secrets are erased. The delivery log stays readable to nobody and ages out with retention.

Path parameters

  • webhook_endpoint_idstringRequired

Response204

Answers 204 with no body.

Status codes

  • 204Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X DELETE "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}" \
  -H "Authorization: Bearer $MDA_API_KEY"
get/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries

List webhook deliveries

Needs webhook.manage

Newest first, kept 30 days. Filters, each repeatable: state (pending, delivering, succeeded, failed, abandoned), event_type (ping for test events), event_id (evt_…: every delivery of one event). Rows carry no body or attempt_log; read one delivery for those.

Path parameters

  • webhook_endpoint_idstringRequired

Query parameters

  • statestring[]
  • event_typestring[]
  • event_idstring[]
  • limitinteger

    Rows per page, 1 to 200.

    Default50at least 1at most 200
  • cursorstring
  • qstring

    Search: rows whose name (or the list's other searchable text) contains this, any case.

    at most 200 characters
  • orderstring

    Sort field; a leading - sorts down. Each list names the fields it sorts by.

    at most 64 charactersmatches ^-?[a-z_]+$
  • includestring[]

    total_count (counted up to 10,000) and facets (a count per filter value).

    One oftotal_countfacets
  • created_afterstring

    Only rows created at or after this time (RFC 3339).

    date-time
  • created_beforestring

    Only rows created at or before this time (RFC 3339).

    date-time
  • updated_afterstring

    Only rows last changed at or after this time (RFC 3339).

    date-time
  • updated_beforestring

    Only rows last changed at or before this time (RFC 3339).

    date-time

Response200

  • objectstring
    list
  • dataWebhookEndpointDelivery[]
    16 fields
    • idstring
    • objectstring
      webhook_delivery
    • attemptsinteger
    • completed_atstring or null
    • created_atstring or null
    • event_idstring
    • event_typestring
    • last_duration_msinteger or null
    • last_error_classstring or null
    • last_status_codeinteger or null
    • next_attempt_atstring or null
    • redelivery_ofstring or null
    • statestring
      One ofpendingdeliveringsucceededfailedabandoned
    • webhook_endpoint_idstring
    • attempt_logWebhookEndpointDeliveryAttempt[] or null
      5 fields
      • atstring or null
      • duration_msinteger or null
      • error_classstring or null
      • ninteger
      • status_codeinteger or null
    • bodyobject or null

      Any JSON object.

  • has_moreboolean
  • next_cursorstring or null
  • facetsmap<string, map<string, integer>> or null
  • peoplemap<string, ActorRef> or null
    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • total_countinteger or null
  • total_count_exactboolean or null

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "object": "list",
  "data": [
    {
      "id": "id",
      "object": "webhook_delivery",
      "attempt_log": [
        {
          "at": "at",
          "duration_ms": 840,
          "error_class": "error class",
          "n": 2,
          "status_code": 2
        }
      ],
      "attempts": 2,
      "body": {},
      "completed_at": "2026-11-10T09:30:00.000Z",
      "created_at": "2026-11-10T09:30:00.000Z",
      "event_id": "evt_01jc0yrbnm84d8zbtsv0h4ksah",
      "event_type": "event type",
      "last_duration_ms": 840,
      "last_error_class": "last error class",
      "last_status_code": 2,
      "next_attempt_at": "2026-11-10T09:30:00.000Z",
      "redelivery_of": "redelivery of",
      "state": "pending",
      "webhook_endpoint_id": "webhook endpoint id"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}
post/v1/webhook_endpoints/{webhook_endpoint_id}/disable

Disable webhook endpoint

Needs webhook.manage

Turns the endpoint off (paused): nothing new is queued for it and deliveries waiting for their next attempt are abandoned.

Path parameters

  • webhook_endpoint_idstringRequired

Response200

  • idstring
  • objectstring
    webhook_endpoint
  • consecutive_failuresinteger
  • created_atstring or null
  • descriptionstring or null
  • disabled_reasonstring or null
    One offailinggone
  • enabledboolean
  • event_typesstring[]
  • failing_sincestring or null
  • last_failure_atstring or null
  • last_success_atstring or null
  • previous_secret_expires_atstring or null
  • row_versioninteger
  • statestring
    One ofpendingactivepauseddisabled
  • updated_atstring or null
  • urlstring
  • workspace_idstring or null
  • created_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • updated_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X POST "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}/disable" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "id": "id",
  "object": "webhook_endpoint",
  "consecutive_failures": 2,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "description": "Reads new support email and drafts a reply.",
  "disabled_reason": null,
  "enabled": true,
  "event_types": [
    "event type"
  ],
  "failing_since": "failing since",
  "last_failure_at": "2026-11-10T09:30:00.000Z",
  "last_success_at": "2026-11-10T09:30:00.000Z",
  "previous_secret_expires_at": "2026-11-10T09:30:00.000Z",
  "row_version": 4,
  "state": "pending",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "url": "https://mcp.example.com/mcp",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}
post/v1/webhook_endpoints/{webhook_endpoint_id}/enable

Enable webhook endpoint

Needs webhook.manage

Turns a paused or disabled endpoint back on after a ping answered with a 2xx; 422 (ping_failed) otherwise. Events raised while it was off are not sent.

Path parameters

  • webhook_endpoint_idstringRequired

Response200

  • idstring
  • objectstring
    webhook_endpoint
  • consecutive_failuresinteger
  • created_atstring or null
  • descriptionstring or null
  • disabled_reasonstring or null
    One offailinggone
  • enabledboolean
  • event_typesstring[]
  • failing_sincestring or null
  • last_failure_atstring or null
  • last_success_atstring or null
  • previous_secret_expires_atstring or null
  • row_versioninteger
  • statestring
    One ofpendingactivepauseddisabled
  • updated_atstring or null
  • urlstring
  • workspace_idstring or null
  • created_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null
  • updated_byActorRef or null

    Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.

    5 fields
    • idstring or null
    • kindstring
      One ofuserapi_keyservice_accountworkloadend_usersystem
    • namestring or null
    • avatar_versionstring or null
    • emailstring or null

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X POST "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}/enable" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "id": "id",
  "object": "webhook_endpoint",
  "consecutive_failures": 2,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "description": "Reads new support email and drafts a reply.",
  "disabled_reason": null,
  "enabled": true,
  "event_types": [
    "event type"
  ],
  "failing_since": "failing since",
  "last_failure_at": "2026-11-10T09:30:00.000Z",
  "last_success_at": "2026-11-10T09:30:00.000Z",
  "previous_secret_expires_at": "2026-11-10T09:30:00.000Z",
  "row_version": 4,
  "state": "pending",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "url": "https://mcp.example.com/mcp",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}
post/v1/webhook_endpoints/{webhook_endpoint_id}/secret

Rotate webhook secret

Needs webhook.manage

A new signing secret, shown this once. For the next 24 hours every delivery carries two v1 signatures, one per secret, so the receiver can switch over without missing an event.

Path parameters

  • webhook_endpoint_idstringRequired

Response200

  • objectstring
    webhook_endpoint_secret
  • previous_secret_expires_atstring or null
  • secretstring
  • webhook_endpoint_idstring

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X POST "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}/secret" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "object": "webhook_endpoint_secret",
  "previous_secret_expires_at": "2026-11-10T09:30:00.000Z",
  "secret": "secret",
  "webhook_endpoint_id": "webhook endpoint id"
}
post/v1/webhook_endpoints/{webhook_endpoint_id}/test

Test webhook endpoint

Needs webhook.manage

Sends one ping event, signed like any other, and answers what the endpoint did (also when it is turned off). Once, no retries; it appears in the delivery log.

Path parameters

  • webhook_endpoint_idstringRequired

Response200

  • objectstring
    webhook_endpoint_test
  • delivery_idstring
  • duration_msinteger or null
  • error_classstring or null
  • okboolean
  • status_codeinteger or null
  • webhook_endpoint_idstring

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X POST "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}/test" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "object": "webhook_endpoint_test",
  "delivery_id": "eml_01jcekn5yqh6nhjfrf1q5xwth8",
  "duration_ms": 840,
  "error_class": "error class",
  "ok": true,
  "status_code": 2,
  "webhook_endpoint_id": "webhook endpoint id"
}
get/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries/{webhook_delivery_id}

Get webhook delivery

Needs webhook.manage

One delivery with the body exactly as sent and every attempt: when, the status code, our error class and how long it took.

Path parameters

  • webhook_endpoint_idstringRequired
  • webhook_delivery_idstringRequired

Response200

  • idstring
  • objectstring
    webhook_delivery
  • attemptsinteger
  • completed_atstring or null
  • created_atstring or null
  • event_idstring
  • event_typestring
  • last_duration_msinteger or null
  • last_error_classstring or null
  • last_status_codeinteger or null
  • next_attempt_atstring or null
  • redelivery_ofstring or null
  • statestring
    One ofpendingdeliveringsucceededfailedabandoned
  • webhook_endpoint_idstring
  • attempt_logWebhookEndpointDeliveryAttempt[] or null
    5 fields
    • atstring or null
    • duration_msinteger or null
    • error_classstring or null
    • ninteger
    • status_codeinteger or null
  • bodyobject or null

    Any JSON object.

Status codes

  • 200Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries/{webhook_delivery_id}" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 200
JSON
{
  "id": "id",
  "object": "webhook_delivery",
  "attempt_log": [
    {
      "at": "at",
      "duration_ms": 840,
      "error_class": "error class",
      "n": 2,
      "status_code": 2
    }
  ],
  "attempts": 2,
  "body": {},
  "completed_at": "2026-11-10T09:30:00.000Z",
  "created_at": "2026-11-10T09:30:00.000Z",
  "event_id": "evt_01jc0yrbnm84d8zbtsv0h4ksah",
  "event_type": "event type",
  "last_duration_ms": 840,
  "last_error_class": "last error class",
  "last_status_code": 2,
  "next_attempt_at": "2026-11-10T09:30:00.000Z",
  "redelivery_of": "redelivery of",
  "state": "pending",
  "webhook_endpoint_id": "webhook endpoint id"
}
post/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries/{webhook_delivery_id}/redeliver

Redeliver webhook

Needs webhook.manage

Sends the same event again as a new delivery (redelivery_of), with the same body and event ID and a fresh signature, retried like any delivery. The endpoint must be on. At most webhooks.redeliveries_per_hour (100) per endpoint (429).

Path parameters

  • webhook_endpoint_idstringRequired
  • webhook_delivery_idstringRequired

Response202

  • idstring
  • objectstring
    webhook_delivery
  • attemptsinteger
  • completed_atstring or null
  • created_atstring or null
  • event_idstring
  • event_typestring
  • last_duration_msinteger or null
  • last_error_classstring or null
  • last_status_codeinteger or null
  • next_attempt_atstring or null
  • redelivery_ofstring or null
  • statestring
    One ofpendingdeliveringsucceededfailedabandoned
  • webhook_endpoint_idstring
  • attempt_logWebhookEndpointDeliveryAttempt[] or null
    5 fields
    • atstring or null
    • duration_msinteger or null
    • error_classstring or null
    • ninteger
    • status_codeinteger or null
  • bodyobject or null

    Any JSON object.

Status codes

  • 202Successful Response
  • 422The request is not valid: errors[] names each field.
  • 4XXThe request was refused: the problem says why.
  • 5XXThe API could not answer: the problem says why.
Request
curl -X POST "https://api.mydeepagents.com/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries/{webhook_delivery_id}/redeliver" \
  -H "Authorization: Bearer $MDA_API_KEY"
Response · 202
JSON
{
  "id": "id",
  "object": "webhook_delivery",
  "attempt_log": [
    {
      "at": "at",
      "duration_ms": 840,
      "error_class": "error class",
      "n": 2,
      "status_code": 2
    }
  ],
  "attempts": 2,
  "body": {},
  "completed_at": "2026-11-10T09:30:00.000Z",
  "created_at": "2026-11-10T09:30:00.000Z",
  "event_id": "evt_01jc0yrbnm84d8zbtsv0h4ksah",
  "event_type": "event type",
  "last_duration_ms": 840,
  "last_error_class": "last error class",
  "last_status_code": 2,
  "next_attempt_at": "2026-11-10T09:30:00.000Z",
  "redelivery_of": "redelivery of",
  "state": "pending",
  "webhook_endpoint_id": "webhook endpoint id"
}

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.