TagPayTagPay

API Reference

Webhook Endpoints

Webhook endpoints are URLs on your server that TagPay POSTs event payloads to. Each endpoint is signed with its own dedicated `signing_secret` — store it on creation and use it to verify the HMAC-SHA512 signature on incoming requests.

Create a webhook endpoint

POST/v1/webhooks

Creates a webhook endpoint. The response includes a signing_secret (prefixed whksec_…) that is returned only once — store it immediately and use it to verify the HMAC-SHA512 signature on each incoming request.

mode is immutable after creation — a test-mode endpoint only receives test-mode events, and likewise for live. Pass events: ["*"] to subscribe to every event type.

Body parameters

modeenum<'test' | 'live'>required

Which mode this endpoint receives events for. Immutable after creation — create separate endpoints for test and live traffic.

urlstringrequired

HTTPS URL TagPay will POST event payloads to.

eventsarray<string>required

Event types to deliver to this endpoint, or ["*"] to subscribe to all events.

Response

200
idstring

Endpoint ID (`whk_…`).

modeenum<'test' | 'live'>

Mode this endpoint receives events for.

urlstring

The URL events will be POSTed to.

eventsarray<string>

Event types this endpoint is subscribed to.

signing_secretstring

HMAC-SHA512 secret for verifying deliveries. **Only returned at creation.**

created_atstring

ISO-8601 creation timestamp.

Errors

INVALID_URL400URL must be a valid HTTPS URL.
INVALID_EVENTS400Events array must be non-empty and contain valid event types.
INVALID_KEY401API key missing or invalid.

List webhook endpoints

GET/v1/webhooks

Returns every webhook endpoint registered on the account, newest first. The signing_secret is never included on list responses — it is only returned at creation.

Response

200
dataarray<WebhookEndpoint>

Registered endpoints, newest first.

idstring

Endpoint ID.

modeenum<'test' | 'live'>

Mode this endpoint receives events for.

urlstring

Delivery URL.

eventsarray<string>

Subscribed event types.

created_atstring

ISO-8601 creation timestamp.

metaobject

Pagination metadata.

totalinteger

Total endpoints.

pageinteger

Current page.

per_pageinteger

Page size.

Errors

INVALID_KEY401API key missing or invalid.

Retrieve a webhook endpoint

GET/v1/webhooks/:id

Returns the endpoint resource. The signing_secret field is never populated on this response — only on the initial create call. Use POST /v1/webhooks/:id/rotate_secret to mint a fresh secret without losing delivery history.

Path parameters

idstringrequired

Webhook endpoint ID (whk_…).

Response

200
idstring

Endpoint ID.

modeenum<'test' | 'live'>

Mode this endpoint receives events for.

urlstring

Delivery URL.

eventsarray<string>

Subscribed event types.

created_atstring

ISO-8601 creation timestamp.

Errors

NOT_FOUND404No webhook endpoint with that ID.
INVALID_KEY401API key missing or invalid.

Delete a webhook endpoint

DELETE/v1/webhooks/:id

Deletes the endpoint. TagPay will stop attempting deliveries immediately.

Path parameters

idstringrequired

Webhook endpoint ID to delete.

Response

200
idstring

Deleted endpoint ID.

deletedboolean

Always `true` on success.

Errors

NOT_FOUND404No webhook endpoint with that ID.
INVALID_KEY401API key missing or invalid.