Roll Webhook Secret

POST

/api/:account_id/webhook-endpoints/:external_id/roll-secret

POST

/api/:account_id/webhook-endpoints/:external_id/roll-secret

$ curl -X POST https://app.paymentkit.com/api/account_id/webhook-endpoints/external_id/roll-secret \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "id": "whe_prod_9f8e7d6c5b4a3210",
3   "url": "https://webhooks.myapp.com/receive",
4   "events": [
5     "payment.succeeded",
6     "payment.failed"
7   ],
8   "is_active": true,
9   "is_protected": false,
10   "is_blacklisted": false,
11   "consecutive_failures": 0,
12   "created_at": "2024-01-10T08:00:00Z",
13   "updated_at": "2024-04-20T12:45:00Z",
14   "signing_secret": "whsec_9a8b7c6d5e4f3g2h1i0jklmnopqrstuv",
15   "description": "Production webhook for payment events",
16   "blacklisted_at": "null",
17   "last_failed_delivery": {
18     "last_response_status": 502,
19     "last_error": "Connection refused",
20     "last_attempt_at": "2024-01-15T09:30:00Z"
21   }
22 }

Roll the signing secret for a webhook endpoint.

The old secret will remain valid for the specified TTL (grace period), allowing clients time to update their configuration.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

external_idstringRequired

account_idstringRequired

Request

This endpoint expects an object.

ttl_secondsintegerOptional0-604800Defaults to 3600

Time in seconds to keep the old secret valid (grace period)

Response

Successful Response

idstring

Unique webhook endpoint identifier

urlstring

The URL receiving webhook events

eventslist of strings

List of subscribed event types

is_activeboolean

Whether the webhook endpoint is active

is_protectedboolean

Whether the webhook endpoint is protected from deletion

is_blacklistedboolean

Whether the webhook endpoint is blacklisted due to consecutive delivery failures

consecutive_failuresinteger

Number of consecutive delivery failures (resets on success)

created_atdatetime

When the webhook endpoint was created

updated_atdatetime

When the webhook endpoint was last updated

signing_secretstring

Signing secret for verifying webhook payloads

descriptionstring or nullOptional

Webhook endpoint description

blacklisted_atdatetime or nullOptional

When the webhook endpoint was blacklisted (null if not blacklisted)

last_failed_deliveryobject or nullOptional

Information about the last failed delivery (only included for blacklisted endpoints)

Errors

422

Unprocessable Entity Error