---
title: "Webhook endpoints"
description: "Manage the URLs OrderCard posts events to."
image: "https://docs.ordercard.io/og.png"
---

> API Reference Index
> Fetch the complete API index at: https://docs.ordercard.io/api/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook endpoints

Webhook endpoints are usually managed in the dashboard, which also shows every delivery and can resend one. These endpoints cover automated set-ups.

Each endpoint belongs to the key's environment and has its own signing secret. Read [Webhooks](/webhooks) for the events and the payload, and [Verifying signatures](/webhooks/signatures) before you trust a delivery.

## List webhook endpoints

`GET /v1/webhook_endpoints`

Lists the endpoints of the key's team and environment.

- **Operation id:** `webhook-endpoints.list`
- **Required ability:** `webhooks:read`
- **Rate limit:** 300 requests/minute per API key

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | 1 to 100, default 25. |
| `cursor` | string | no | The meta.next_cursor of the previous page. |

#### Request

```bash
curl https://api.ordercard.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — A page of endpoints. Signing secrets are not included.

```json
{ "data": [ {
    "object": "webhook_endpoint",
    "id": "we_01jaxsd2f5h8k1m4p7r0t3w6y9",
    "url": "https://shop.example.com/webhooks/ordercard",
    "description": "Order system",
    "events": ["transaction.succeeded", "transaction.declined"],
    "active": true,
    "environment": "live",
    "created_at": "2026-10-17T15:30:00+00:00",
    "updated_at": "2026-10-17T15:30:00+00:00"
  } ], "links": { "...": "..." }, "meta": { "...": "..." } }
```

## Add a webhook endpoint

`POST /v1/webhook_endpoints`

Adds an endpoint. The response is the only API answer that includes its signing secret; the dashboard can reveal it later.

- **Operation id:** `webhook-endpoints.create`
- **Required ability:** `webhooks:write`
- **Rate limit:** 300 requests/minute per API key

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | A public http or https URL. Private, internal and unresolvable addresses are refused. Example: `https://shop.example.com/webhooks/ordercard` |
| `description` | string | no | Your label, max 255 characters. |
| `events` | array<string> | yes | Event types to receive, or ["*"] for all of them, including types added later: payment_method.created, payment_method.updated, payment_method.redacted, transaction.succeeded, transaction.declined, transaction.failed. |
| `active` | boolean | no | An inactive endpoint receives nothing. |

#### Request

```bash
curl -X POST https://api.ordercard.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://shop.example.com/webhooks/ordercard", "events": ["transaction.succeeded", "transaction.declined"] }'
```

#### Responses

##### 201 — The endpoint, with its secret.

```json
{
  "object": "webhook_endpoint",
  "id": "we_01jaxsd2f5h8k1m4p7r0t3w6y9",
  "url": "https://shop.example.com/webhooks/ordercard",
  "description": "Order system",
  "events": ["transaction.succeeded", "transaction.declined"],
  "active": true,
  "secret": "whsec_8sK2…",
  "environment": "live",
  "created_at": "2026-10-17T15:30:00+00:00",
  "updated_at": "2026-10-17T15:30:00+00:00"
}
```

##### 422 — The URL is not public.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Webhooks only go to public http or https addresses. This URL is private, internal or does not resolve.",
    "errors": { "url": ["Webhooks only go to public http or https addresses. This URL is private, internal or does not resolve."] }
  }
}
```

## Retrieve a webhook endpoint

`GET /v1/webhook_endpoints/{id}`

Returns one endpoint, without its secret.

- **Operation id:** `webhook-endpoints.get`
- **Required ability:** `webhooks:read`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The endpoint's id. Example: `we_01jaxsd2f5h8k1m4p7r0t3w6y9` |

#### Request

```bash
curl https://api.ordercard.io/v1/webhook_endpoints/we_01jaxsd2f5h8k1m4p7r0t3w6y9 \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — The endpoint.

```json
{
  "object": "webhook_endpoint",
  "id": "we_01jaxsd2f5h8k1m4p7r0t3w6y9",
  "url": "https://shop.example.com/webhooks/ordercard",
  "description": "Order system",
  "events": ["transaction.succeeded", "transaction.declined"],
  "active": true,
  "environment": "live",
  "created_at": "2026-10-17T15:30:00+00:00",
  "updated_at": "2026-10-17T15:30:00+00:00"
}
```

## Update a webhook endpoint

`PATCH /v1/webhook_endpoints/{id}`

Changes the URL, description, events or active flag. Only the fields you send change.

- **Operation id:** `webhook-endpoints.update`
- **Required ability:** `webhooks:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The endpoint's id. Example: `we_01jaxsd2f5h8k1m4p7r0t3w6y9` |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | A public http or https URL. Private, internal and unresolvable addresses are refused. Example: `https://shop.example.com/webhooks/ordercard` |
| `description` | string | no | Your label, max 255 characters. |
| `events` | array<string> | no | Event types to receive, or ["*"] for all of them, including types added later: payment_method.created, payment_method.updated, payment_method.redacted, transaction.succeeded, transaction.declined, transaction.failed. |
| `active` | boolean | no | An inactive endpoint receives nothing. |

#### Request

```bash
curl -X PATCH https://api.ordercard.io/v1/webhook_endpoints/we_01jaxsd2f5h8k1m4p7r0t3w6y9 \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["*"] }'
```

#### Responses

##### 200 — The updated endpoint.

```json
{
  "object": "webhook_endpoint",
  "id": "we_01jaxsd2f5h8k1m4p7r0t3w6y9",
  "url": "https://shop.example.com/webhooks/ordercard",
  "description": "Order system",
  "events": ["transaction.succeeded", "transaction.declined"],
  "active": true,
  "environment": "live",
  "created_at": "2026-10-17T15:30:00+00:00",
  "updated_at": "2026-10-17T15:30:00+00:00"
}
```

## Remove a webhook endpoint

`DELETE /v1/webhook_endpoints/{id}`

Removes the endpoint and its delivery history.

- **Operation id:** `webhook-endpoints.delete`
- **Required ability:** `webhooks:write`
- **Rate limit:** 300 requests/minute per API key

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The endpoint's id. Example: `we_01jaxsd2f5h8k1m4p7r0t3w6y9` |

#### Request

```bash
curl -X DELETE https://api.ordercard.io/v1/webhook_endpoints/we_01jaxsd2f5h8k1m4p7r0t3w6y9 \
  -H "Authorization: Bearer $ORDERCARD_SECRET_KEY"
```

#### Responses

##### 200 — Confirmation.

```json
{ "object": "webhook_endpoint", "id": "we_01jaxsd2f5h8k1m4p7r0t3w6y9", "deleted": true }
```

Source: https://docs.ordercard.io/api/webhook-endpoints/index.mdx