Create a webhook endpoint

POST/v1/webhook_endpoints

Registers a URL and returns its signing secret. Store the secret right away: it isn't shown again. You can have up to 10 endpoints per environment.

Permissions: Secret key with webhooks:manage.

Guide

Webhooks

Request headers#

Idempotency-Keystring
Any string up to 255 characters; use a UUID v4. Kept 24 hours per key (or member) and endpoint. Same key and body replays the first response with Idempotent-Replayed: true.
Max Length 255

Request body#

urlstring (uri)Required
HTTPS URL on a public hostname. IP addresses, localhost and private networks are refused.
event_typesarray of stringRequired
Event types to send, or ["*"] for all.
Min Items 1
descriptionstring
Your label, up to 255 characters.
Max Length 255

Response fields#

Returns 201 with WebhookEndpoint

idstring (uuid)
The endpoint's id.
urlstring (uri)
Where events are sent. HTTPS on a public hostname.
descriptionstringNullable
Your label, up to 255 characters.
Max Length 255
event_typesarray of string
Types this endpoint gets, or ["*"] for all types, including types added later. See Webhook event types.
statusstring
enabled or disabled. unPLUG sets disabled after 3 days of failed deliveries.
One of enabled, disabled
secretstring
The signing secret, whsec_ followed by base64. Returned only when you create the endpoint or rotate the secret.
created_atstring (date-time)
When the endpoint was created.
updated_atstring (date-time)
When the endpoint last changed.

POST/v1/webhook_endpoints

1
2
3
4
5
6
7
8
9curl -X POST https://api.unplugdining.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b8e5f2a-6c1d-4a97-b3e4-9d7f2c5a8e10" \
  -d '{
    "url": "https://api.example.com/webhooks/unplug",
    "event_types": ["points.changed", "tier.changed", "reward.issued", "member.deleted"],
    "description": "Loyalty sync"
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14const response = await fetch("https://api.unplugdining.com/v1/webhook_endpoints", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "0b8e5f2a-6c1d-4a97-b3e4-9d7f2c5a8e10",
  },
  body: JSON.stringify({
    url: "https://api.example.com/webhooks/unplug",
    event_types: ["points.changed", "tier.changed", "reward.issued", "member.deleted"],
    description: "Loyalty sync",
  }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import os
import requests

response = requests.post(
    "https://api.unplugdining.com/v1/webhook_endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
        "Idempotency-Key": "0b8e5f2a-6c1d-4a97-b3e4-9d7f2c5a8e10",
    },
    json={
        "url": "https://api.example.com/webhooks/unplug",
        "event_types": [
            "points.changed",
            "tier.changed",
            "reward.issued",
            "member.deleted",
        ],
        "description": "Loyalty sync",
    },
)
data = response.json()

Response JSON201

1
2
3
4
5
6
7
8
9
10{
  "id": "1c7f4a9e-3d2b-4f86-a5e1-8b0d6c3f9e72",
  "url": "https://api.example.com/webhooks/unplug",
  "description": "Loyalty sync",
  "event_types": ["points.changed", "tier.changed", "reward.issued", "member.deleted"],
  "status": "enabled",
  "secret": "whsec_4cWtG7hYe5kSMHqAFDTiyxca6HNalvlQ",
  "created_at": "2026-11-02T14:51:30Z",
  "updated_at": "2026-11-02T14:51:30Z"
}

Error descriptions#

400Bad request

missing_param

url or event_types is missing.

400Bad request

invalid_param

The URL isn't HTTPS on a public hostname, or an event type doesn't exist. param names the field.

400Bad request

invalid_request

You already have 10 endpoints in this environment.

Any endpoint can also return the common errors.

400 Bad request

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#missing_param",
  "title": "Bad request",
  "status": 400,
  "code": "missing_param",
  "detail": "url or event_types is missing."
}