---
title: "Receive a pending webhook event without a public endpoint"
method: POST
path: "/endpoints/{id}/pull"
tags: ["Endpoints"]
---

# Receive a pending webhook event without a public endpoint

`POST /endpoints/{id}/pull`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/endpoints/{id}/pull`
- Auth: HTTP bearer

Wait up to 30 seconds for one existing event. The body string preserves the exact webhook serialization; headers and canonical occurrence/type metadata travel alongside it. A fixed lease protects the attempt while a short handler accepts input. Retry may redeliver an occurrence: deduplicate event_id. Empty delivery means no offer now, not proof all input was delivered; inspect backlog and persistent gap_count/last_gap_reason. Queue retention is 24 hours and does not extend source-content retention. Disconnecting preserves pending work. Same named destination shares consumption; different destinations get independent copies.

## Headers

- `Idempotency-Key` string

## Request body

- PullWebhookInput
  - `wait_seconds` integer

## Response `200`

Delivery operation result

- PullWebhookResponse
  - `success` true, required
  - `data` object, required
    - `delivery` object, nullable, required
      - `queue_id` string, uuid, required
      - `event_id` string, uuid, required
      - `event_type` string, required
      - `delivery_id` string, uuid, required
      - `lease_token` string, uuid, required
      - `lease_expires_at` string, date-time, required
      - `body` string, nullable, required: The webhook body, exactly as serialized. Null when your access to the mailbox shows headers only (metadata depth): this field carries message content.
      - `headers` object, required
    - `backlog` integer, required
    - `gap_count` integer, required
    - `last_gap_reason` string, nullable, required
    - `retention_seconds` 86400, required
    - `handler_timeout_seconds` 30, required
  - `meta` object
    - `total` number
    - `total_capped` boolean
    - `limit` number
    - `cursor` string, nullable

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `404`: Resource not found
- `408`: Request was canceled
- `409`: The request conflicts with the current state of the resource
- `410`: Queued content is no longer available
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.
- `503`: Local receiving is unavailable

## Changes

> 32 revisions in range; 1 not diffed.

- **2026-11-03** `bce409c97acb`: 1 breaking, 279 warning
  - the response property `data/delivery/body` became nullable for the status `200`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `400`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `401`
  - added the new `access_mode_unavailable` enum value to the `error/code` response property for the response status `403`
  - …276 more
  - …this revision’s changelog is incomplete
- **2026-10-21** `0360ea8d4f3d`: 117 warning
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `400`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `401`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `403`
  - added the new `agent_changed` enum value to the `error/code` response property for the response status `404`
  - …113 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/primitive/apis/primitive-api/changes/endpoints/:id/pull/post.md)

---

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