---
title: "Create Polling Webhook"
method: POST
path: "/v0/pods/{pod_id}/webhooks/polling"
tags: ["pods > webhooks > polling"]
---

# Create Polling Webhook

`POST /v0/pods/{pod_id}/webhooks/polling`

## Request

- Base URL: `https://api.agentmail.to`
- URL: `https://api.agentmail.to/v0/pods/{pod_id}/webhooks/polling`
- Auth: HTTP bearer

Create a polling webhook scoped to this pod and return the `token` that reads it.

**CLI:**
```bash
agentmail pods webhooks polling create --pod-id <pod_id> --client-id my-agent --event-types message.received
```

## Path parameters

- `pod_id` string, required: ID of pod.

## Request body

- WebhooksPollingCreatePodPollingWebhookRequest: Create a polling webhook scoped to a pod. The pod comes from the path, so `pod_ids` is not accepted. Optionally pass `inbox_ids` to narrow the subscription to specific inboxes within the pod; omit to receive events for the whole pod.
  - `client_id` string, required: Client ID of webhook.
  - `event_types` EventsEventType[], required: Event types for which to send events.
  - `inbox_ids` string[]: Inboxes for which to send events.

## Response `200`

Response with status 200

- WebhooksPollingCreatePollingWebhookResponse: The subscription plus the one-time `token` that reads it.
  - `webhook_id` string, required: ID of webhook.
  - `client_id` string, required: Client ID of webhook.
  - `event_types` EventsEventType[], required: Event types for which to send events.
  - `pod_ids` string[]: Pods for which to send events.
  - `inbox_ids` string[]: Inboxes for which to send events.
  - `pod_id` string: ID of the pod the subscription belongs to: the pod it was created in, or the pod of the inbox it belongs to. Absent for an organization subscription. This is not the list of pods it receives events for; see `pod_ids`.
  - `inbox_id` string: ID of the inbox the subscription belongs to, if it was created for an inbox. This is not the list of inboxes it receives events for; see `inbox_ids`.
  - `updated_at` string, date-time, required: Time at which the subscription was last updated.
  - `created_at` string, date-time, required: Time at which the subscription was created.
  - `token` string, required: Credential for reading this subscription's events. Hand it to the Svix AutoConfig consumer (`AutoConfigConsumer` in the `svix` package for TypeScript and Python): `receive` returns the events queued since your last commit, `commit` marks them as processed. Returned by create only and never readable afterward. Create again with the same `client_id` to get a new token; the previous one stops working immediately.

## Other responses

- `400`: Error response with status 400
- `409`: Error response with status 409

## Changes

- **2026-10-16** `3f5c7830c952`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/pods/:pod_id/webhooks/polling/post.md)

---

[API](https://skmtc.dev/agentmail-to/apis/api.md) - [All operations](https://skmtc.dev/agentmail-to/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentmail-to/apis/api/revisions/a9792efe7bdf?raw)