Create Webhook Endpoint

POST

/api/:account_id/webhook-endpoints/

POST

/api/:account_id/webhook-endpoints/

$ curl -X POST https://app.paymentkit.com/api/account_id/webhook-endpoints/ \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "url": "https://webhooks.myshop.com/order-updates",
>   "events": [
>     "payment.succeeded",
>     "payment.failed"
>   ]
> }'

1 {
2   "id": "whe_prod_9f8e7d6c5b4a3210",
3   "url": "https://webhooks.myshop.com/order-updates",
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-06-10T12:00:00Z",
13   "updated_at": "2024-06-10T12:00:00Z",
14   "signing_secret": "whsec_4f5e6d7c8b9a0f1e2d3c4b5a6e7f8d9c",
15   "description": "Production webhook for payment events",
16   "blacklisted_at": "contextually null since not blacklisted",
17   "last_failed_delivery": {
18     "last_response_status": 0,
19     "last_error": "null",
20     "last_attempt_at": "null"
21   }
22 }

Create a new webhook endpoint. The signing secret is only returned once at creation time. Store it securely as it cannot be retrieved again.

Authentication

AuthorizationBearer

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

Path parameters

account_idstringRequired

Request

This endpoint expects an object.

urlstringRequired

The URL to receive webhook events

eventslist of stringsRequired

List of event types to subscribe to

descriptionstring or nullOptional<=500 characters

Optional description for the webhook endpoint

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