Rotate the signing secret

POST/v1/webhook_endpoints/{id}/rotate_secret

Creates a new signing secret and returns it once. Until the current secret expires, every request is signed with both secrets, so webhook-signature carries two v1 entries. See Rotate the signing secret in the guide.

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

Path parameters#

idstring (uuid)Required

Request body#

expire_current_in_hoursinteger
How long the current secret keeps signing. Default 24. Use 0 if the secret leaked.
Min 0Default 24

Response fields#

Returns 200 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/{id}/rotate_secret

1
2
3
4curl -X POST https://api.unplugdining.com/v1/webhook_endpoints/1c7f4a9e-3d2b-4f86-a5e1-8b0d6c3f9e72/rotate_secret \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expire_current_in_hours": 24 }'

1
2
3
4
5
6
7
8
9const response = await fetch("https://api.unplugdining.com/v1/webhook_endpoints/1c7f4a9e-3d2b-4f86-a5e1-8b0d6c3f9e72/rotate_secret", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ expire_current_in_hours: 24 }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11import os
import requests

response = requests.post(
    "https://api.unplugdining.com/v1/webhook_endpoints/1c7f4a9e-3d2b-4f86-a5e1-8b0d6c3f9e72/rotate_secret",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
    json={"expire_current_in_hours": 24},
)
data = response.json()

Response JSON200

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", "communication_preferences.updated"],
  "status": "enabled",
  "secret": "whsec_Qm9xT2pW7cR1nL5vY8kH3dZ6sA0fJ4gE",
  "created_at": "2026-11-02T14:51:30Z",
  "updated_at": "2026-11-20T16:02:47Z"
}

Error descriptions#

400Bad request

invalid_param

expire_current_in_hours is negative or not a whole number.

404Not found

not_found

No endpoint with this id 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#invalid_param",
  "title": "Bad request",
  "status": 400,
  "code": "invalid_param",
  "detail": "expire_current_in_hours is negative or not a whole number."
}