Webhook configuration - DCS Technical Documentation

📄 Guide

Whether you are an exchange, a wallet or a platform, webhooks let you mirror the key DCS events, card lifecycle, transaction authorization, KYC and tickets, into your own system in real time, without the cost of polling. As a licensed issuer, DCS signs every webhook it sends, so verifying the signature is all it takes to confirm that an event really came from DCS. This page covers two things: how to get DCS to push events to your callback URL (configuration and whitelisting), and how to verify that each push is genuine (the HMAC signature). For the event types and the field structure of each event, see Events and data structures.

1. Configure the callback URLs

Who does it: webhook configuration is currently done by DCS on your behalf; there is no self-service configuration endpoint yet. Please send the information below through your integration group chat or your business contact.

There are two callback URLs to give DCS:

URL	Purpose	What is pushed
`webhookUrl`	Business event notifications	Card order status, card status, KYC tickets, tickets, authorization results (asynchronous)
`authUrl`	Authorization forwarding notifications	Real-time authorization requests (DCS waits synchronously for you to return approve or decline)

authUrl carries the real-time decision under Partner-Managed and is protected by RSA two-way signing and encryption, which makes it a channel entirely separate from the business webhooks (HMAC-signed) described on this page. For the security model of authUrl, see Real-time authorization; for how to hand over the callback URLs and the public key, see First steps.

Requirements for the callback URLs

They must use https and resolve to an IP that is reachable from the public internet.
They must be registrable in the DCS webhook whitelist, so send DCS your egress addresses as well (separately for sandbox and production).
Expose a stable, long-lived path; URLs that change often lead to missed deliveries.

Who does it (you): DCS operates a webhook whitelist. Sandbox and production are two independent configurations, so submit the addresses for each; otherwise you will find a gap on go-live day.

2. Verify the signature (HMAC-SHA256)

To keep the channel secure, DCS includes X-Signature in the headers of every webhook request. The signature is produced with HmacSHA256 using your secretKey as the key. Before you process the payload you must recompute the signature over the raw payload as received with the same algorithm and confirm that it matches X-Signature; only then is the request proven genuine and untampered.

Request headers

Header	Description
`X-Signature`	The HMAC-SHA256 signature DCS computed over the raw payload (hex encoded)
`Content-Type`	Always `application/json`

Always compute over the raw bytes: the HMAC has to be computed over the raw payload string DCS sent. If you parse the JSON and regenerate it, field order, whitespace and escaping can all change, the signature will differ and verification will fail. Read and buffer the raw body for verification before you parse it. DCS sends compact JSON with the fields at every level sorted lexicographically by full field name, and new fields may be added in the future — none of this affects verification as long as you verify the raw payload. See Events and schema · Notes.

Verification example

The Java example DCS provides (computing the HMAC-SHA256 of the payload):

import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

class HmacSignature {

    public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
        String secretKey = "secret_key";
        String webhookPayloadStr = "webhook_Payload_Str"; // the raw payload string as received
        byte[] hmacSha256;
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(secretKeySpec);
        hmacSha256 = mac.doFinal(webhookPayloadStr.getBytes());
        // compare against the X-Signature request header
        System.out.println(Hex.encodeHexString(hmacSha256));
    }
}

The check passes when Hex(HmacSHA256(secretKey, raw payload)) and X-Signature are identical character for character. Use a constant-time comparison to avoid a timing side channel.

secretKey comes from the same source as apiKey; together they are the integration credentials DCS issues to you. For how to retrieve them securely for production, see Authentication. Treat secretKey as a secret, keep it server-side only, and never ship it to a front end or a client app.

3. Response and consumption conventions

So that no event is lost and none is processed twice, we recommend the following conventions:

Item	Convention	Notes
Success response	Return HTTP `200` (any 2xx counts as success)	Acknowledge quickly on receipt, then process the business logic asynchronously, to avoid timing out
Idempotent deduplication	Key on `webhookId`	The same event may be delivered more than once, so check `webhookId` for duplicates before processing
Retry on failure	Up to 3 attempts for general events	Driven by a scheduled job, with the backoff interval following that job’s configuration; the real-time `AUTHORISATION` channel is never retried and a timeout is declined outright
Out-of-order arrival	Order by `notificationTime`	The network and retries can deliver events out of order, so use the timestamp in the payload to reconstruct the true sequence

For the meaning of the shared fields such as webhookId and notificationTime, see Events and data structures.

Avoid returning an HTML or plain-text error page: return a structured response even when processing fails (or acknowledge with 2xx and retry asynchronously); it makes troubleshooting and redelivery tracking far easier.

Next steps

Once signature verification works end to end, move on to Events and data structures, parse each event’s data field by webhookType, and wire it into your business logic.

​📄 Guide

​1. Configure the callback URLs

​Requirements for the callback URLs

​2. Verify the signature (HMAC-SHA256)

​Request headers

​Verification example

​3. Response and consumption conventions

​Next steps

📄 Guide

1. Configure the callback URLs

Requirements for the callback URLs

2. Verify the signature (HMAC-SHA256)

Request headers

Verification example

3. Response and consumption conventions

Next steps