# Retrieve Webhooks

`POST /webhooks`

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

## Authentication

Send your API key in the `PINNACLE-API-KEY` header.

## Request body

Required.

Content type: `application/json`.

### Fields

- `identifiers` — `string[]`. List of URLs or phone numbers in E.164 format that the webhook is attached to.

**Limit:** 1 min

### Example

```json
{
  "identifiers": [
    "https://www.pinnacle.sh/payment",
    "+14155678901",
    "https://www.pinnacle.sh/sms-callback",
    "+14153456659"
  ]
}
```

## Responses

### 200

Returns all webhooks matching the search criteria.

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`.

Content type: `application/json`. Schema: `WebhookResult`.

- `webhooks` — `object[]`. List of webhooks.
- `webhooks[].endpoint` — `string`. URL where webhook events are delivered.
- `webhooks[].id` — `string`. The unique identifier of the webhook. This identifier is a string that always begins with the prefix `wh_`, for example: `wh_1234567890`.
- `webhooks[].name` — `string`. Name of the webhook.
- `webhooks[].headers` — `object`, optional. 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.

Example:

```json
{
  "webhooks": [
    {
      "id": "wh_1234567890",
      "name": "Payment Notification Webhook",
      "endpoint": "https://www.pinnacle.sh/examples/check-payment",
      "headers": {
        "X-API-KEY": "sk_live_..."
      }
    },
    {
      "id": "wh_1234567890",
      "name": "SMS Delivery Webhook",
      "endpoint": "https://www.pinnacle.sh/examples/talk-to-my-friends",
      "headers": null
    }
  ]
}
```

### 400

Validation failed. The payload has missing required fields and/or invalid types.

See https://zod.dev/error-formatting for more information.

Content type: `application/json`. Schema: `object`.

- `description` — `string`. Human-readable summary of validation failures.
- `errors` — `object`. Structured dictionary of issues containing two main sections:
- `errors`: Array of global validation errors not tied to specific fields
- `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

Example:

```json
{
  "description": "✖ Invalid input: expected string, received number\n  → at example_field",
  "errors": {
    "errors": [
      "Unrecognized key: 'extraKey'"
    ],
    "properties": {
      "example_field": {
        "errors": [
          "Invalid input: expected string, received NaN"
        ]
      }
    }
  }
}
```

### 401

The request lacks valid authentication credentials or the provided credentials are invalid.

Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Invalid API key."
}
```

### 403

Your subscription does not include access to this feature.

This occurs when attempting to use functionality that requires a higher subscription tier.
Please upgrade your subscription to access this feature.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Your subscription does not include access to this feature."
}
```

### 500

An unexpected error occurred on Pinnacle's servers while processing your request.

If this error persists, please contact support with the request details.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "An unexpected error occurred while processing your request."
}
```

## SDK examples

### TypeScript

```typescript
import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.webhooks.get({
    identifiers: ["https://www.pinnacle.sh/payment", "+14155678901", "https://www.pinnacle.sh/sms-callback", "+14153456659"]
});
```

### Python

```python
import os
from rcs import Pinnacle

client = Pinnacle(
    api_key=os.environ["PINNACLE_API_KEY"],
)

client.webhooks.get(
    identifiers=[
        "https://www.pinnacle.sh/payment",
        "+14155678901",
        "https://www.pinnacle.sh/sms-callback",
        "+14153456659",
    ],
)
```

### Ruby

```ruby
require "rcs"

client = Pinnacle::Client.new(
  api_key: ENV.fetch("PINNACLE_API_KEY")
)

client.webhooks.get(identifiers: %w[https://www.pinnacle.sh/payment +14155678901 https://www.pinnacle.sh/sms-callback +14153456659])
```

## Machine-readable schema

[OpenAPI 3.1 JSON](https://docs.pinnacle.sh/openapi.json)