curl -X POST https://secureapi.tender.cash/v1/api/webhook \
-H "x-access-id: $TENDER_ACCESS_ID" \
-H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
-H "x-timestamp: 2026-10-15T09:45:53.000Z" \
-H "authorization: pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0=" \
-H "Content-Type: application/json" \
-d '{
"description": "Production webhook",
"url": "https://your-domain.com/webhooks/tender",
"eventTypes": ["transaction_completed", "transaction_cancelled"],
"headers": { "X-Webhook-Secret": "a-long-random-value" }
}'
{
"status": "success",
"message": "success",
"data": {
"_id": "691069ff947a702cfad9e861",
"merchantId": "6538e8f9bdec6d1a21978a64",
"description": "Production webhook",
"url": "https://your-domain.com/webhooks/tender",
"eventTypes": ["transaction_completed", "transaction_cancelled"],
"headers": { "X-Webhook-Secret": "a-long-random-value" },
"isActive": true,
"isDeleted": false,
"createdAt": "2026-10-15T10:16:31.594Z",
"updatedAt": "2026-10-15T10:18:35.286Z"
}
}
{
"status": "error",
"message": "Webhook URL must use https",
"data": null
}
Webhooks
Add Webhook
Register or replace the webhook endpoint for your merchant account
POST
/
v1
/
api
/
webhook
curl -X POST https://secureapi.tender.cash/v1/api/webhook \
-H "x-access-id: $TENDER_ACCESS_ID" \
-H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
-H "x-timestamp: 2026-10-15T09:45:53.000Z" \
-H "authorization: pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0=" \
-H "Content-Type: application/json" \
-d '{
"description": "Production webhook",
"url": "https://your-domain.com/webhooks/tender",
"eventTypes": ["transaction_completed", "transaction_cancelled"],
"headers": { "X-Webhook-Secret": "a-long-random-value" }
}'
{
"status": "success",
"message": "success",
"data": {
"_id": "691069ff947a702cfad9e861",
"merchantId": "6538e8f9bdec6d1a21978a64",
"description": "Production webhook",
"url": "https://your-domain.com/webhooks/tender",
"eventTypes": ["transaction_completed", "transaction_cancelled"],
"headers": { "X-Webhook-Secret": "a-long-random-value" },
"isActive": true,
"isDeleted": false,
"createdAt": "2026-10-15T10:16:31.594Z",
"updatedAt": "2026-10-15T10:18:35.286Z"
}
}
{
"status": "error",
"message": "Webhook URL must use https",
"data": null
}
Auth method: Signed (HMAC) — this endpoint requires the full set of signed
headers:
x-access-id, x-request-id, x-timestamp, and an HMAC-SHA256
authorization signature. See Authentication.Headers
string
required
Base64-encoded HMAC-SHA256 signature of
{"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}, signed with your access secret. The request body is not part of the signature.Example: "pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0="string
required
ISO 8601 timestamp; must be within 5 minutes of server timeExample:
"2026-10-15T09:45:53.000Z"string
required
A unique UUID v4 per requestExample:
"550e8400-e29b-41d4-a716-446655440000"string
required
Your API access ID provided by TenderExample:
"your-access-id-here"string
required
Media type of the request bodyExample:
"application/json"description, url, eventTypes and headers; the webhook keeps its _id. See Webhooks for delivery behaviour.
Body
All four fields are required.string
required
A description for your own referenceExample:
"Production webhook"string
required
The URL Tender sends events to. It must use
https, and must not point to localhost or a private, loopback or link-local address.Example: "https://your-domain.com/webhooks/tender"string[]
required
The events to receive. Names are lowercase and case-sensitive, and aren’t checked: a misspelt name is accepted but never delivered. Get valid names from List Webhook Events or see Webhook Events. Send an empty array to stop deliveries without deleting the webhook.Example:
["transaction_completed", "transaction_cancelled"]object
required
Custom headers Tender sends with every delivery, as string key-value pairs. Use them to authenticate deliveries, because webhooks are not signed.
Host, Content-Length, Connection, Transfer-Encoding, Upgrade, Proxy-Authorization and X-Forwarded-* headers are not sent.Example: { "X-Webhook-Secret": "a-long-random-value" }Response
Returns HTTP200 with the saved webhook.
string
required
Always
"success"string
required
Example:
"success"object
required
The saved webhook. Additional fields may be present; ignore fields you don’t recognise.
Show data properties
Show data properties
string
The webhook ID. Use it with Delete Webhook.Example:
"691069ff947a702cfad9e861"string
Your merchant IDExample:
"6538e8f9bdec6d1a21978a64"string
Description of the webhookExample:
"Production webhook"string
Webhook endpoint URLExample:
"https://your-domain.com/webhooks/tender"string[]
Subscribed event namesExample:
["transaction_completed", "transaction_cancelled"]object
Custom headers sent with every deliveryExample:
{ "X-Webhook-Secret": "a-long-random-value" }boolean
Always
true for a registered webhookExample: truestring
ISO 8601 timestamp when the webhook was first registeredExample:
"2026-10-15T10:16:31.594Z"string
ISO 8601 timestamp when the webhook was last changedExample:
"2026-10-15T10:18:35.286Z"Errors
| Status | When |
|---|---|
400 | A field is missing or has the wrong type, or the URL is not allowed, for example "Webhook URL must use https". |
401, 403 | See Authentication. |
429 | Rate limit exceeded. |
curl -X POST https://secureapi.tender.cash/v1/api/webhook \
-H "x-access-id: $TENDER_ACCESS_ID" \
-H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
-H "x-timestamp: 2026-10-15T09:45:53.000Z" \
-H "authorization: pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0=" \
-H "Content-Type: application/json" \
-d '{
"description": "Production webhook",
"url": "https://your-domain.com/webhooks/tender",
"eventTypes": ["transaction_completed", "transaction_cancelled"],
"headers": { "X-Webhook-Secret": "a-long-random-value" }
}'
{
"status": "success",
"message": "success",
"data": {
"_id": "691069ff947a702cfad9e861",
"merchantId": "6538e8f9bdec6d1a21978a64",
"description": "Production webhook",
"url": "https://your-domain.com/webhooks/tender",
"eventTypes": ["transaction_completed", "transaction_cancelled"],
"headers": { "X-Webhook-Secret": "a-long-random-value" },
"isActive": true,
"isDeleted": false,
"createdAt": "2026-10-15T10:16:31.594Z",
"updatedAt": "2026-10-15T10:18:35.286Z"
}
}
{
"status": "error",
"message": "Webhook URL must use https",
"data": null
}
Authorizations
Signed (HMAC) authentication. Required headers: x-access-id, x-request-id (UUID v4), x-timestamp (ISO 8601, must be within 5 minutes of server time), and authorization: the Base64 HMAC-SHA256 of the JSON string {"timeStamp":"","requestId":"","accessId":""} (keys in that order, no whitespace) using your access secret. The request body, method and path are not signed. The API key must be linked to an outlet.
Headers
Base64-encoded HMAC-SHA256 signature of {"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}, signed with your access secret. The request body is not part of the signature.
ISO 8601 timestamp; must be within 5 minutes of server time
A unique UUID v4 per request
Your API access ID provided by Tender
Media type of the request body
Available options:
application/json Body
application/json
A description for your own reference
Example:
"Production webhook"
Public HTTPS URL. Must not point to localhost or a private, loopback or link-local address.
Example:
"https://your-domain.com/webhooks/tender"
Event names to receive (lowercase, case-sensitive). Names are not validated on subscribe.
Available options:
transaction_completed, transaction_overpayment, transaction_partially_paid, transaction_partial_fulfilled, transaction_requested, transaction_reserved, transaction_cancelled, sub_user_wallet_transaction_detected, sub_user_wallet_transfer_confirmed, sub_user_wallet_transfer_failed, offramp_order_completed, offramp_order_cancelled, offramp_order_failed Example:
[ "transaction_completed", "transaction_cancelled" ]
Custom headers sent with every delivery. Use them to authenticate deliveries.
Show child attributes
Show child attributes
Example:
{ "X-Webhook-Secret": "a-long-random-value" }