---
title: "Retrieve Webhooks"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Retrieve Webhooks

`POST /webhooks`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/webhooks`
- Auth: API key in header `PINNACLE-API-KEY`

Retrieve all webhook that are set up to receive events for specific URLs or phone numbers.

## Request body

- GetWebhooksSchema
  - `identifiers` string[], required: List of URLs or phone numbers in E.164 format that the webhook is attached to. <br><br> **Limit:** 1 min

## Response `200`

Returns all webhooks matching the search criteria. <br>

Results are sorted by ID and duplicates are removed. This identifier is a string that always begins with the prefix `wh_`, for example: `wh_1234567890`.

- WebhooksResponse: Response containing all webhooks that match the requested identifiers. Only includes the essential webhook information needed for identification and management.
  - `webhooks` Webhooks[], required: List of webhooks.
    - `endpoint` string, required: URL where webhook events are delivered.
    - `id` string, required: The unique identifier of the webhook. This identifier is a string that always begins with the prefix `wh_`, for example: `wh_1234567890`.
    - `name` string, required: Name of the webhook.
    - `headers` object, nullable: Optional custom HTTP headers sent on every webhook delivery. Header names must match the regex `^[A-Za-z0-9][A-Za-z0-9_-]*$` — start with a letter or digit and contain only letters, digits, `-`, or `_`. Keys are case-insensitive and stored in uppercase. Values must be strings. The reserved `PINNACLE-SIGNING-SECRET` header is never returned here and cannot be overridden.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)