Get started

TRANSACTION_UPDATED

TRANSACTION_UPDATED is sent whenever a transaction is created or changes. It is the event you will rely on most.

When it is sent

Scenario	Trigger
Gift card, hosted payment model	The customer pays on the page from `paymentLink` and Spendstream issues the card.
Gift card, float model	A call to `giftCardRequestApi` issues a card from your prepaid balance.
Affiliate	A transaction is recorded, or its status or commission changes, for example from pending to approved. These are sent by the Spendstream dashboard rather than the API.

Each gift card purchase sends one webhook. If you have more than one webhook URL or API key pair registered, each one receives its own copy, so deduplicate as described below.

⚠️ Warning: An affiliate transaction can change several times before it is final. Treat every delivery as the latest known state of that transaction, and never assume a pending transaction is settled.

Request format

The request is an HTTP POST with a multipart/form-data body, not a raw JSON body.

Field	Type	Description
`eventType`	string	Always `TRANSACTION_UPDATED` for this event.
`transaction`	string	A JSON-encoded string describing the transaction. Decode it after reading the form field.

Headers:

Header	Description
`Signature`	Hexadecimal HMAC-SHA256 signature. See Webhook security.
`TimeStamp`	The time the webhook was signed, `YYYY-MM-DD HH:MM:SS` in UTC. Part of the signed string.

The header names are exactly Signature and TimeStamp. There is no Spendstream- prefix.

Example: hosted payment

HTTP

 POST /webhooks/spendstream HTTP/1.1
Content-Type: multipart/form-data; boundary=------------------------7d1f
Signature: 3f2c9a...example...b71d
TimeStamp: 2026-10-08 10:15:00

--------------------------7d1f
Content-Disposition: form-data; name="eventType"

TRANSACTION_UPDATED
--------------------------7d1f
Content-Disposition: form-data; name="transaction"

{"UID":"12345","brand-name":"Example Brand","date":"2026-10-08 10:14:58","transaction-id":"a03823e0-316b-11f0-aecc-73ec0aa304a8","order-id":"17872646666a877e9aee2bf","amount-spend":"10.00","total-spendAmount":"10.00","total-commission":"0.00","total-comission":"0.00","gift-card-url":"https://example-publisher.dev.spendstream.co/gift-card-url/20","gift-card-expiry-date":"2027-10-08 23:59:59","free-entries":0,"transaction-type":"gateway"}
--------------------------7d1f--

Gift card fields

Field	Float (`giftCardRequestApi`)	Hosted payment (`paymentLink`)	Meaning
`UID`	Yes	Yes	Your identifier for the user.
`brand-name`	Yes	Yes	Brand of the card issued.
`date`	Yes	Yes	Time the card was issued, in UTC.
`transaction-id`	Yes	Yes	Spendstream’s reference for the card. Use it to deduplicate.
`order-id`	Empty	Yes	The `order-id` that `paymentLink` returned. Use it to match your order.
`amount-spend`	Yes	Yes	Face value of the card.
`total-spendAmount`	Sometimes	Yes	Same value as `amount-spend`.
`total-commission`	Yes	Yes	Commission on this purchase.
`gift-card-url`	Yes	Yes	Where the user views and redeems the card. Send this to your customer.
`gift-card-expiry-date`	No	Yes	Card expiry.
`free-entries`	Yes	Yes	Free entries earned, for prize-draw publishers. Otherwise `0`.
`transaction-type`	`float`	`gateway`	How the card was paid for.
`available-balance`	Sometimes	No	Your prepaid balance after the purchase.
`promo-id`, `brand-id`, `userwalet`	No	Sometimes	Promotion, brand and the user’s reward balances.

total-comission is a legacy misspelling of total-commission that is still sent for compatibility. Read total-commission.

Other fields may also appear, sometimes empty. They are used only by white-label sites. Ignore any field you do not recognise.

💡 Tip: The payment success page response uses different names from the webhook: giftcard-url, user-id and giftcard-face-value (now also purchase-amount). Build your fulfilment on the webhook fields above, not on the success page.

Handling the event

Verify the signature and timestamp first.
Read eventType, then decode the transaction JSON string.
For hosted payments, find your order using order-id. Then deliver gift-card-url to the customer.
Upsert the record using transaction-id as the key, so a repeated delivery changes nothing.
Return 200 quickly.

There is no event identifier, so deduplicate on transaction-id plus its status. See Webhook processing best practices.

Related reference

Status values are described in the API reference for getTransactionsList and getTransactionsById.
Use getTransactionsList for periodic reconciliation, because failed deliveries are not retried.

Sections