Receive an issuer card-tokenization webhook
Receives a signed webhook from the card issuer carrying raw card material for a card the server already owns, then tokenizes that material in-flight and persists only the resulting reference ids. No card number or security code is ever persisted or logged.
Signature scheme: Each request carries two headers that must both be present:
card-issuer-signature— base64url-encoded HMAC-SHA256 over the canonical string"{timestamp}.{url}.{body}", signed with the configured issuer webhook secret.card-issuer-signature-timestamp— unix epoch seconds at which the issuer signed the request.
Timestamp tolerance: Requests with a timestamp more than 300 seconds from server time are rejected before HMAC compute, in either direction.
Failure modes:
A missing or invalid signature returns 401 with error code CRD-401-001. The
detail is a fixed string and never echoes the client-supplied signature or
timestamp. Successful delivery returns 200; replays of the same eventId are
accepted as 200 no-ops so the issuer’s retries are safe. Handler exceptions
surface as 5xx so the issuer will retry.
Headers
Controls how timestamp fields are serialized in JSON response bodies.
Default (header omitted or any other value): epoch milliseconds as integers.
iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.
Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".
Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.
Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.
"iso8601"
Body
Response
Webhook received
Acknowledgement returned for every accepted webhook delivery (incl. no-op replays).