Skip to content
ZTLDeveloper Portal

Create webhook subscription

POST
/api/webhooks/subscription
Code sample: Shell / cURL
curl --request POST \
  --url https://api.ztlpay.io/api/webhooks/subscription \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "targetUrl": "https://partner.example/webhooks/ztl", "eventTypes": [ "PAYMENT_STATUS" ], "bearerToken": "example" }'

Creates an enabled subscription. Earlier events are not replayed. The API access token authenticates this request; the optional bearerToken authenticates deliveries to your endpoint.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
targetUrl
required

Public HTTPS endpoint with a host and no embedded username or password. Requires a valid publicly trusted TLS certificate. Use the test endpoint to verify reachability.

string format: uri
Example
https://partner.example/webhooks/ztl
eventTypes
required
Array<string>
>= 1 items unique items
Allowed values: PAYMENT_STATUS PAYMENT_STATUS_UNSIGNED PAYMENT_STATUS_IN_PROGRESS PAYMENT_STATUS_REJECTED PAYMENT_STATUS_COMPLETED PAYMENT_STATUS_CANCELLED PAYMENT_STATUS_CUSTOMER_ACTION_REQUIRED
bearerToken

Optional non-blank token value without the Bearer prefix. Omit or use null for no bearer authentication. ZTL adds the Bearer prefix to the Authorization header on delivery.

string | null
>= 1 characters

Responses

Section titled “Responses”

201

Section titled “201”

Subscription created. Store the returned signing secret securely.

Media typeapplication/json
object
id
required
string format: uuid
targetUrl
required
string format: uri
enabled
required
boolean
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
eventTypes
required
Array<string>
unique items
Allowed values: PAYMENT_STATUS PAYMENT_STATUS_UNSIGNED PAYMENT_STATUS_IN_PROGRESS PAYMENT_STATUS_REJECTED PAYMENT_STATUS_COMPLETED PAYMENT_STATUS_CANCELLED PAYMENT_STATUS_CUSTOMER_ACTION_REQUIRED
hasBearerToken
required
boolean
signingSecret
required

Store securely. It is only returned when creating or rotating a signing secret.

string
Example
{
  "eventTypes": [
    "PAYMENT_STATUS"
  ]
}

400

Section titled “400”

Invalid target URL, event type, or bearer token.