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.
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.
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.
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.
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.
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.
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.
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. Token status notifications (PAYMENT_TOKENIZATION) are the exception: notificationTime does not reflect the order in which token statuses changed, so do not order them by it. The source of truth for a token’s latest status is List the tokens of a card
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.
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.
Assistant
Responses are generated using AI and may contain mistakes.
