Integration Guide
How it works
UC-Card signs the signature and sends card data to the third-party agent webhook URL. The agent verifies the signature first: if it is correct, process the data and reply 200. If it is not correct, reply 401.
What you receive
HTTP POST with a JSON body and these headers:
| Header | Meaning |
|---|---|
Content-Type | Always application/json. |
X-Event | Type of event, same as event_type in the body. |
X-Event-ID | Unique ID of the event, same as event_id in the body. |
X-Timestamp | Unix time in seconds when the request was signed. |
X-Signature | The signature (base64 text). |
The envelope is identical for every event; compare event_type and data. See Event Types for every event and its example body.
{
"agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
"data": { "...": "depends on event_type" },
"event_at": "2026-10-16T08:00:25.121447Z",
"event_id": "d06d711a-dced-5c36-8e2c-7ccbb4e48bc9",
"event_type": "card.request.result",
"version": "1"
}
How to verify the signature
signature = base64( HMAC-SHA256( secret, timestamp + "\n" + rawBody ) )
- Read the raw body exactly as received. Do not parse and re-save the JSON first.
- Join
X-Timestamp, a newline character (\n) and the raw body (timestamp first, then body). - Compute HMAC-SHA256 with your secret and convert to base64.
- Compare with
X-Signature. If equal, the data is correct.
The same signature rule applies to all event types.
What you reply
| Status | When |
|---|---|
200 | The signature is correct and you accepted the data. Reply quickly (within 10 seconds), then process in the background. |
401 | Signature is not correct, or the X-Signature or X-Timestamp header is missing. Do not process the data. |
400 | The body could not be read or is not valid JSON. |
Retries
Any 2xx reply counts as delivered. Any other reply, a timeout (10 seconds) or a connection error is retried, up to 5 attempts in total:
| Attempt | Sent |
|---|---|
| 1 | Immediately |
| 2 | After 1 minute |
| 3 | After 5 minutes |
| 4 | After 30 minutes |
| 5 | After 2 hours |
A retry sends the same body and the same event_id with a new X-Timestamp and X-Signature. Because a retry can arrive even after you processed the first attempt, always de-duplicate by event_id.
Checklist
- Use the raw body for the signature, not a re-built JSON.
- Compare signatures with a constant-time function (
hmac.Equalor similar). - Save
event_idand ignore an event you already processed. - Route by
event_typeand ignore event types you do not handle (still reply200) so new types do not cause retries. - Treat amounts as decimal strings and
otp/activation_codeas text. - Use HTTPS for your webhook URL and keep the secret private.
Example agent code (Go)
A short Go agent that receives the callback on POST /webhook, checks the signature, and routes by event_type. Replace the secret with your own.
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/json"
"errors"
"io"
"log"
"net/http"
)
const maxBodyBytes = 1024 * 1024 // 1 MB
type Event struct {
EventID string `json:"event_id"`
EventType string `json:"event_type"`
Version string `json:"version"`
EventAt string `json:"event_at"`
AgentID string `json:"agent_id"`
Data json.RawMessage `json:"data"`
}
func reply(w http.ResponseWriter, status int, body any) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(body)
}
func webhookHandler(secret []byte) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
reply(w, http.StatusNotFound, map[string]string{"error": "Use POST /webhook"})
return
}
timestamp := r.Header.Get("X-Timestamp")
signature := r.Header.Get("X-Signature")
if timestamp == "" || signature == "" {
reply(w, http.StatusUnauthorized, map[string]string{"error": "Missing signature headers"})
return
}
// Read the exact bytes received, capped at 1 MB.
rawBody, err := io.ReadAll(http.MaxBytesReader(w, r.Body, maxBodyBytes))
if err != nil {
var tooLarge *http.MaxBytesError
if errors.As(err, &tooLarge) {
reply(w, http.StatusRequestEntityTooLarge, map[string]string{"error": "Payload exceeds 1 MB"})
return
}
reply(w, http.StatusBadRequest, map[string]string{"error": "Failed to read request"})
return
}
// Verify the raw bytes before parsing JSON: HMAC-SHA256(timestamp + "\n" + body).
mac := hmac.New(sha256.New, secret)
mac.Write([]byte(timestamp + "\n"))
mac.Write(rawBody)
expected := mac.Sum(nil)
received, err := base64.StdEncoding.DecodeString(signature)
// hmac.Equal is constant-time and returns false on length mismatch.
if err != nil || !hmac.Equal(received, expected) {
log.Println("Rejected callback: invalid signature")
reply(w, http.StatusUnauthorized, map[string]string{"error": "Invalid signature"})
return
}
var ev Event
if err := json.Unmarshal(rawBody, &ev); err != nil {
reply(w, http.StatusBadRequest, map[string]string{"error": "Invalid JSON"})
return
}
// TODO: skip if ev.EventID was already processed (store it in your database).
switch ev.EventType {
case "card.request.result", "card.top_up.result", "card.withdrawal.result",
"card.status.update.result", "card.update.result":
log.Printf("Operation result %s: %s", ev.EventType, ev.Data)
case "card.3ds.otp", "card.verification.otp", "card.activation.code":
// Contains a code: forward it to the cardholder, do not log it.
log.Printf("Code event %s received for %s", ev.EventType, ev.EventID)
case "card.activation.status", "card.fee":
log.Printf("%s: %s", ev.EventType, ev.Data)
default:
// card.transaction.* and any future event type.
log.Printf("Event %s: %s", ev.EventType, ev.Data)
}
reply(w, http.StatusOK, map[string]bool{"received": true})
}
}
func main() {
secret := "<your-webhook-secret>" // replace with your own secret
port := "8080"
mux := http.NewServeMux()
mux.HandleFunc("/webhook", webhookHandler([]byte(secret)))
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
reply(w, http.StatusNotFound, map[string]string{"error": "Use POST /webhook"})
})
addr := "127.0.0.1:" + port
log.Printf("Listening on http://%s/webhook", addr)
log.Fatal(http.ListenAndServe(addr, mux))
}