# Porkbun API v3 — Webhooks

> Register HTTPS endpoints to receive signed, real-time event notifications. See the Webhooks section in the introduction for the payload envelope and signature-verification recipe.

Part of the Porkbun API v3.7. Topic index: https://porkbun.com/llms · Full reference: https://porkbun.com/llms-full.txt · Overview: https://porkbun.com/llms.txt · OpenAPI spec: https://porkbun.com/api/json/v3/spec

**Auth:** send `X-API-Key` / `X-Secret-API-Key` headers (preferred) or `apikey` / `secretapikey` in the JSON body. Create keys at https://porkbun.com/account/api

---

# Endpoints

## GET /api/json/v3/webhook/eventTypes

**List subscribable event types**

Return the catalog of event types a webhook endpoint can subscribe to. Read-only; supports GET (header auth) or POST (body or header auth).

| Parameter | In | Required | Description |
|---|---|---|---|
| `Authorization` | header | no | Bearer token: `Authorization: Bearer <token>` |
| `X-API-Key` | header | no | API key header auth (use with X-Secret-API-Key) |
| `X-Secret-API-Key` | header | no | Secret API key header auth (use with X-API-Key) |

```bash
curl 'https://api.porkbun.com/api/json/v3/webhook/eventTypes' \
  -H 'X-API-Key: pk1_...' \
  -H 'X-Secret-API-Key: sk1_...'
```

Response fields (WebhookEventTypesResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `eventTypes` | string[] |  |

## GET /api/json/v3/webhook/list

**List webhook endpoints**

List all webhook endpoints registered on the authenticated account, including each endpoint's signing secret and delivery health. Read-only; supports GET (header auth) or POST (body or header auth).

| Parameter | In | Required | Description |
|---|---|---|---|
| `Authorization` | header | no | Bearer token: `Authorization: Bearer <token>` |
| `X-API-Key` | header | no | API key header auth (use with X-Secret-API-Key) |
| `X-Secret-API-Key` | header | no | Secret API key header auth (use with X-API-Key) |

```bash
curl 'https://api.porkbun.com/api/json/v3/webhook/list' \
  -H 'X-API-Key: pk1_...' \
  -H 'X-Secret-API-Key: sk1_...'
```

Response fields (WebhookListResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `endpoints` | object[] |  |

## GET /api/json/v3/webhook/get/{id}

**Get a webhook endpoint**

Fetch a single webhook endpoint by id, including its signing secret and delivery health. Read-only; supports GET (header auth) or POST (body or header auth).

| Parameter | In | Required | Description |
|---|---|---|---|
| `id` | path | yes |  |
| `Authorization` | header | no | Bearer token: `Authorization: Bearer <token>` |
| `X-API-Key` | header | no | API key header auth (use with X-Secret-API-Key) |
| `X-Secret-API-Key` | header | no | Secret API key header auth (use with X-API-Key) |

```bash
curl 'https://api.porkbun.com/api/json/v3/webhook/get/42' \
  -H 'X-API-Key: pk1_...' \
  -H 'X-Secret-API-Key: sk1_...'
```

Response fields (WebhookEndpointResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `endpoint` | object |  |

## POST /api/json/v3/webhook/create

**Create a webhook endpoint**

Register an HTTPS endpoint to receive signed event payloads. The response includes the generated `secret` — store it securely; it is the HMAC key used to verify the `X-Porkbun-Signature` header. Omit `events` (or pass `["*"]`) to subscribe to all event types. Maximum 20 endpoints per account.

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | HTTPS URL to deliver events to. |
| `events` | string[] | no | Event types to subscribe to. Omit, or pass ["*"], for all events. Prefix wildcards like "dns.*" are allowed. |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/webhook/create \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","url":"https://example.com/porkbun/webhook","events":["*"]}'
```

Response fields (WebhookEndpointResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `endpoint` | object |  |

## POST /api/json/v3/webhook/update

**Update a webhook endpoint**

Update an endpoint's URL, event subscriptions, and/or status. Only the supplied fields change. Set `status` to `DISABLED` to pause deliveries or `ACTIVE` to resume (resuming also resets the consecutive-failure counter).

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Endpoint id to update. |
| `url` | string | no | New HTTPS URL (optional). |
| `events` | string[] | no | Replacement event subscription list (optional). |
| `status` | string | no | Set ACTIVE to resume (also clears the failure counter) or DISABLED to pause (optional). |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/webhook/update \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","id":42,"status":"DISABLED"}'
```

Response fields (WebhookEndpointResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `endpoint` | object |  |

## POST /api/json/v3/webhook/rotateSecret

**Rotate the signing secret**

Generate a new signing secret for an endpoint and return the endpoint with the new secret. Deliveries are signed with the new secret immediately, so update your verifier as part of the same operation.

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Endpoint id. |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/webhook/rotateSecret \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","id":42}'
```

Response fields (WebhookEndpointResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `endpoint` | object |  |

## POST /api/json/v3/webhook/test

**Send a test event**

Enqueue a `webhook.test` event to the endpoint so you can confirm reachability and that your signature verification works. The endpoint must be ACTIVE. Delivery is asynchronous (usually within a minute).

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Endpoint id. |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/webhook/test \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","id":42}'
```

Response fields (WebhookTestResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `eventId` | string | UUID of the queued webhook.test event. |
| `message` | string |  |

## POST /api/json/v3/webhook/delete

**Delete a webhook endpoint**

Delete a webhook endpoint by id. Deliveries stop immediately.

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Endpoint id. |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/webhook/delete \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","id":42}'
```

Response fields:

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `message` | string |  |

## GET /api/json/v3/webhook/deliveries

**List webhook deliveries**

List recent delivery attempts across the account (newest first), optionally filtered by endpoint or status. The bulky payload is omitted — use GET /webhook/delivery/{id} for it. History is retained about 30 days. Read-only; supports GET (header auth) or POST (body or header auth).

| Parameter | In | Required | Description |
|---|---|---|---|
| `endpointId` | query | no | Only deliveries for this endpoint. |
| `status` | query | no | Filter by delivery status. |
| `start` | query | no | Pagination offset (default 0). |
| `limit` | query | no | Page size, 1-200 (default 50). |
| `Authorization` | header | no | Bearer token: `Authorization: Bearer <token>` |
| `X-API-Key` | header | no | API key header auth (use with X-Secret-API-Key) |
| `X-Secret-API-Key` | header | no | Secret API key header auth (use with X-API-Key) |

```bash
curl 'https://api.porkbun.com/api/json/v3/webhook/deliveries?status=FAILED&limit=50' \
  -H 'X-API-Key: pk1_...' \
  -H 'X-Secret-API-Key: sk1_...'
```

Response fields (WebhookDeliveryListResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `deliveries` | object[] | Newest first. The bulky `payload` field is omitted here. |
| `total` | integer | Total matching deliveries (for pagination). |
| `start` | integer | Offset of this page. |
| `limit` | integer | Page size used. |
| `message` | string |  |

## GET /api/json/v3/webhook/delivery/{id}

**Get a webhook delivery**

Fetch a single delivery including the full event payload that was (or will be) sent and its delivery status. Read-only; supports GET (header auth) or POST (body or header auth).

| Parameter | In | Required | Description |
|---|---|---|---|
| `id` | path | yes |  |
| `Authorization` | header | no | Bearer token: `Authorization: Bearer <token>` |
| `X-API-Key` | header | no | API key header auth (use with X-Secret-API-Key) |
| `X-Secret-API-Key` | header | no | Secret API key header auth (use with X-API-Key) |

```bash
curl 'https://api.porkbun.com/api/json/v3/webhook/delivery/9001' \
  -H 'X-API-Key: pk1_...' \
  -H 'X-Secret-API-Key: sk1_...'
```

Response fields (WebhookDeliveryResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `delivery` | object |  |

## POST /api/json/v3/webhook/resend

**Resend a delivery**

Re-queue a past delivery to its endpoint. Clones it into a fresh attempt reusing the ORIGINAL event id (so consumers that dedupe on X-Porkbun-Webhook-Id treat it as the same event). The endpoint must still exist and be ACTIVE. The original delivery row is left intact as history.

Request body fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Endpoint id. |

```bash
curl -X POST https://api.porkbun.com/api/json/v3/webhook/resend \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","id":9001}'
```

Response fields (WebhookResendResponse):

| Field | Type | Description |
|---|---|---|
| `status` | string |  |
| `delivery` | object |  |
| `message` | string |  |

---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://github.com/oborseth/Porkbun-MCP (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api