> ## Documentation Index
> Fetch the complete documentation index at: https://agentmail.manicule.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://agentmail.manicule.dev/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://agentmail.manicule.dev/api/mcp.
> Every agent surface: https://agentmail.manicule.dev/.well-known/llms-manifest.json

# Create Webhook (/api-reference/create-webhook-2)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 2127 · updated: 2026-09-29 -->
Related: [Sign Up](/api-reference/sign-up.md), [Attach Human](/api-reference/attach-human.md), [Verify](/api-reference/verify.md), [List Inboxes](/api-reference/list-inboxes.md), [Create Inbox](/api-reference/create-inbox.md), [Search Inboxes](/api-reference/search-inboxes.md)

# Create Webhook

`POST /v0/webhooks`

> **CLI:**
> ```bash
> agentmail webhooks create --url https://example.com/webhook --event-types message.received
> ```

Base URL: `https://api.agentmail.to`

Base URL: `https://x402.api.agentmail.to`

Base URL: `https://mpp.api.agentmail.to`

Base URL: `https://api.agentmail.eu`

## OpenAPI

```json
{
  "servers": [
    {
      "url": "https://api.agentmail.to",
      "description": "prod"
    },
    {
      "url": "https://x402.api.agentmail.to",
      "description": "prod-x402"
    },
    {
      "url": "https://mpp.api.agentmail.to",
      "description": "prod-mpp"
    },
    {
      "url": "https://api.agentmail.eu",
      "description": "eu-prod"
    }
  ],
  "security": [
    {
      "Bearer": []
    }
  ],
  "securitySchemes": {
    "Bearer": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "URL of webhook endpoint.",
              "title": "Url"
            },
            "event_types": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "message.received",
                  "message.received.spam",
                  "message.received.blocked",
                  "message.received.unauthenticated",
                  "message.sent",
                  "message.delivered",
                  "message.bounced",
                  "message.complained",
                  "message.rejected",
                  "message.opened",
                  "domain.verified"
                ],
                "title": "EventType"
              },
              "description": "Event types for which to send events.",
              "title": "EventTypes"
            },
            "client_id": {
              "type": "string",
              "description": "Client ID of webhook.",
              "title": "ClientId"
            },
            "headers": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              },
              "description": "Custom HTTP headers to include with every delivery to this webhook. Header values are write-only:\nAgentMail never returns them from webhook read endpoints. The map must contain at least one entry\nwhen provided, and every name and value must be a valid HTTP header.",
              "title": "WebhookHeaders"
            },
            "inbox_ids": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Inboxes for which to send events. Maximum 10 per webhook.",
              "title": "InboxIds"
            },
            "pod_ids": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Pods for which to send events. Maximum 10 per webhook.",
              "title": "PodIds"
            }
          },
          "required": [
            "url",
            "event_types"
          ],
          "title": "CreateWebhookRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Response with status 200",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "webhook_id": {
                "type": "string",
                "description": "ID of webhook.",
                "title": "WebhookId"
              },
              "url": {
                "type": "string",
                "description": "URL of webhook endpoint.",
                "title": "Url"
              },
              "event_types": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "message.received",
                    "message.received.spam",
                    "message.received.blocked",
                    "message.received.unauthenticated",
                    "message.sent",
                    "message.delivered",
                    "message.bounced",
                    "message.complained",
                    "message.rejected",
                    "message.opened",
                    "domain.verified"
                  ],
                  "title": "EventType"
                },
                "description": "Event types for which to send events.",
                "title": "EventTypes"
              },
              "pod_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Pods for which to send events. Maximum 10 per webhook.",
                "title": "PodIds"
              },
              "inbox_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Inboxes for which to send events. Maximum 10 per webhook.",
                "title": "InboxIds"
              },
              "pod_id": {
                "type": "string",
                "description": "ID of the pod the webhook belongs to: the pod it was created in, or the pod of the inbox it\nbelongs to. Absent for an organization webhook and on some inbox webhooks. This is not the\nlist of pods it receives events for; see `pod_ids`."
              },
              "inbox_id": {
                "type": "string",
                "description": "ID of the inbox the webhook belongs to, if it was created for an inbox. This is not the list\nof inboxes it receives events for; see `inbox_ids`."
              },
              "secret": {
                "type": "string",
                "description": "Secret for webhook signature verification."
              },
              "enabled": {
                "type": "boolean",
                "description": "Webhook is enabled."
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "description": "Time at which webhook was last updated."
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "description": "Time at which webhook was created."
              },
              "client_id": {
                "type": "string",
                "description": "Client ID of webhook.",
                "title": "ClientId"
              }
            },
            "required": [
              "webhook_id",
              "url",
              "secret",
              "enabled",
              "updated_at",
              "created_at"
            ],
            "title": "Webhook"
          }
        }
      }
    },
    "400": {
      "description": "Error response with status 400",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of error.",
                "title": "ErrorName"
              },
              "code": {
                "type": "string",
                "description": "Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.",
                "title": "ErrorCode"
              },
              "message": {
                "type": "string",
                "description": "Error message.",
                "title": "ErrorMessage"
              },
              "errors": {
                "description": "Validation errors. Each entry has a path and a message identifying the invalid field."
              },
              "fix": {
                "type": "string",
                "description": "The concrete next action that resolves the error.",
                "title": "ErrorFix"
              },
              "docs": {
                "type": "string",
                "description": "Link to the error reference entry for this code.",
                "title": "ErrorDocs"
              }
            },
            "required": [
              "name",
              "errors"
            ],
            "title": "ValidationErrorResponse"
          }
        }
      }
    }
  }
}
```