Webhooks

Integration Guide

How to receive card data from UC-Card on your webhook URL and check that it is correct.

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.

UC-Card webhook delivery: UC-Card signs the event and POSTs it to the third-party agent. The agent verifies the signature. If it is correct, reply 200 and process the data. If it is not correct, reply 401 and do not process it. Any reply other than 2xx is retried up to 5 times with the same event_id.UC-CardThird-party agentSign & sendSignature · card dataVerify signatureHMAC-SHA256 · base64200 · CorrectAccept · process later401 · Not correctDo not processPOSTCorrectNot correctNot 2xx → retry up to 5× · same event_id

What you receive

HTTP POST with a JSON body and these headers:

HeaderMeaning
Content-TypeAlways application/json.
X-EventType of event, same as event_type in the body.
X-Event-IDUnique ID of the event, same as event_id in the body.
X-TimestampUnix time in seconds when the request was signed.
X-SignatureThe 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

StatusWhen
200The signature is correct and you accepted the data. Reply quickly (within 10 seconds), then process in the background.
401Signature is not correct, or the X-Signature or X-Timestamp header is missing. Do not process the data.
400The 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:

AttemptSent
1Immediately
2After 1 minute
3After 5 minutes
4After 30 minutes
5After 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.Equal or similar).
  • Save event_id and ignore an event you already processed.
  • Route by event_type and ignore event types you do not handle (still reply 200) so new types do not cause retries.
  • Treat amounts as decimal strings and otp / activation_code as 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))
}
Copyright © 2026