How webhooks work
Step 1: Set up your server
Before creating a webhook, your server must be ready to receive POST requests. Here’s a minimal example:2xx status code to acknowledge receipt. Any other status code will be treated as a failure and trigger retries.Step 2: Register your webhook
Once your server is ready, register your endpoint:We validate your URL
https://. HTTP URLs are rejected.We send a ping
ping event is POSTed immediately to your URL (header X-KemyCard-Event: ping, 10-second timeout). Answer it with 200.This ping is signed, but with the secret you only receive in the response to this request, so you cannot verify it yet. A ping carries no data: acknowledge it without verification, as in the examples above. If your server rejects it with 401 or 403 because the signature cannot be checked, registration still succeeds (your URL is reachable). Any other status, a timeout or an invalid TLS certificate makes registration fail.Endpoint is created
Step 3: You’re ready
That’s it. From now on, every time an event you subscribed to occurs, we’ll POST it to your URL with the full payload and signature headers.Available events (45)
Subscribe to specific events, or use"*" to receive everything.
Webhook payload format
Every webhook delivery is wrapped in this envelope:Event payloads
Below is the detaileddata payload for each event, along with when it is triggered.
KYC events
kyc.approved
kyc.approved
verified level. The verification is billed at this moment (see balance.debited, reason: kyc_verification).verified_identity is the identity read on the document. identity_mismatch is true when it differs from the identity you declared for this customer (name or date of birth). In that case status is restricted and a kyc.identity_mismatch event follows.kyc.identity_mismatch
kyc.identity_mismatch
restricted by KemyCard and cannot be used until you call POST /kyc/{customerCode}/synchronize. The activate endpoint does not lift this restriction.kyc.identity_synchronized
kyc.identity_synchronized
POST /kyc/{customerCode}/synchronize. The declared identity now matches the verified identity and the restriction is lifted.kyc.rejected
kyc.rejected
POST /kyc/{customerCode}/link to let the customer retry.kyc.expired
kyc.expired
kyc.resubmission_requested
kyc.resubmission_requested
kyc.pending_review
kyc.pending_review
kyc.approved or kyc.rejected event follows.POA events
poa.approved
poa.approved
full level. The verification is billed at this moment (see balance.debited, reason: poa_verification).poa.rejected
poa.rejected
verified. Submit a new document with POST /poa/{customerCode}/document to retry. If the document is genuine but does not show the customer’s full name, open a support ticket from your secure KemyCard account with the customer_code (priority channel); to follow up, email hi@kemycard.com with your ticket number.Card events
Every card event carries the same base fields, plus the fields specific to the event:card.activated
card.activated
POST /cards has been issued and is ready to use. Call GET /cards/{code}/sensitive to get its number, CVV and expiry.card.creation_failed
card.creation_failed
POST /cards could not be issued. The card is failed and everything that was debited (initial load and fees) is refunded to the same cards_visa or cards_mastercard balance.card.topup.completed
card.topup.completed
POST /cards/{code}/topup has been applied. balance is the new card balance.card.topup.failed
card.topup.failed
cards_visa or cards_mastercard balance.card.transaction
card.transaction
transaction object has the same format as GET /cards/{code}/transactions; balance is the card balance after the operation.transaction.type values: settle (payment), auth, decline, refund, fee, auth_fee, fx_fee.card.3ds_request
card.3ds_request
card.wallet_activation_code instead. The event carries the one-time code your customer must enter on the merchant page: relay it to your customer immediately, it is only valid for a few minutes. KemyCard does not send it to your customer.card.wallet_activation_code
card.wallet_activation_code
last_four and external_reference tell you which card and which customer it is for. digital_wallet is Apple Pay, Google Pay or Samsung Pay when the wallet is known, otherwise null.card.annual_fee_charged
card.annual_fee_charged
cards_visa balance at the price of your plan, even if the balance is too low. annual_fee.balance_after can therefore be negative, which suspends your account (see Negative balance and suspension).card.frozen
card.frozen
POST /cards/{code}/freeze. Payments are declined until it is unfrozen. The payload is the base card payload, with status: frozen.card.unfrozen
card.unfrozen
POST /cards/{code}/unfreeze. The payload is the base card payload, with status: active.card.withdrawal.completed
card.withdrawal.completed
POST /cards/{code}/withdraw is completed. The base card payload (with the new balance) plus withdrawal_id, amount (withdrawn from the card), fee (card withdrawal fee of your plan), net_amount (credited to your balance) and credited_balance (cards_visa or cards_mastercard).card.withdrawal.failed
card.withdrawal.failed
card.termination_pending
card.termination_pending
POST /cards/{code}/terminate, or the card provider started closing the card. The card is cancelling: no more top-ups. You receive card.terminated once it is closed.card.terminated
card.terminated
cards_visa or cards_mastercard balance, minus the card provider fee and, if you requested the termination, the card termination fee of your plan; any top-up still in progress is refunded (see card.topup.failed). Use card_code, customer_code and your external_reference to update the right customer in your system. Extra fields: refunded_amount (credited to your balance), card_balance_at_closure, provider_fee, termination_fee.Wallet events
wallet.deposit_received
wallet.deposit_received
customer_code and external_reference are null for a deposit sent directly to your former collection address (before October 22, 2026). In that case balance is the balance of that former collection account.Collect wallet: fee is always 0 and net_amount equals amount. balance is the balance right after the deposit: if it reaches $3, the whole balance is forwarded right away and you receive wallet.forward_completed.wallet.withdrawal_completed
wallet.withdrawal_completed
POST /wallets/{code}/withdrawals, has been sent on the blockchain.wallet.withdrawal_failed
wallet.withdrawal_failed
amount, fees included, is credited back to the wallet. A temporary sending problem does not trigger this event: the withdrawal stays processing and is retried automatically.wallet.withdrawal_completed.wallet.forward_completed
wallet.forward_completed
wallet.forward_failed
wallet.forward_failed
wallet.forward_completed once it is sent.wallet.forward_completed. A forward is never sent twice: while it is under_review, nothing is sent again automatically.wallet.destination_updated
wallet.destination_updated
PATCH /wallets/{code}/destination. An email is also sent to the email address of your account.Virtual account events
Every virtual account event carriesvirtual_account_code, customer_code, external_reference and currency. See Create a virtual account for the statuses and List deposits for the deposit flow.
virtual_account.tos_required
virtual_account.tos_required
tos_url: they must accept the terms themselves. If you gave a tos_redirect_url, they are sent back to it afterwards. Sent once per account. The redirect is not a confirmation: wait for virtual_account.activated.virtual_account.activated
virtual_account.activated
deposit_instructions: the bank details to share with the payer.virtual_account.failed
virtual_account.failed
others ops balance.virtual_account.closed
virtual_account.closed
POST /virtual-accounts/{code}/close. It no longer accepts deposits.creation_fee_refunded is the creation fee when the account was closed before its bank details were issued, 0 otherwise.virtual_account.deposit_received
virtual_account.deposit_received
virtual_account.transfer_completed
virtual_account.transfer_completed
wallet destination) or sent on-chain and confirmed by the blockchain (external_address destination). Until the transaction is confirmed, the deposit stays sending.virtual_account.transfer_failed
virtual_account.transfer_failed
external_address destination), or the blockchain rejected the transaction. The funds did not leave. Our team is notified and retries the transfer.Gift card events
gift_card.delivered
gift_card.delivered
gift_card.failed
gift_card.failed
gift_card.refunded
gift_card.refunded
Payout events
Thedata of every payout event is the payout object, the same as GET /payouts/{code}. The same events are sent for SEPA payouts (rail sepa) and ACH payouts to the United States (rail ach). For an ACH payout, received_currency is USD, amount_eur and exchange_rate are null, balance_type is others and the beneficiary shows account_number_masked and routing_number instead of iban_masked. See the Payouts guide.
The examples below are SEPA payouts.
payout.processing
payout.processing
processing. With SEPA Instant, funds usually arrive within minutes. An ACH transfer can take a few business days.payout.completed
payout.completed
completed, completed_at is set.payout.failed
payout.failed
failed. The refund to the balance that paid the payout (Payout SEPA, or Ops Others for ACH) follows automatically, with payout.refunded.payout.refunded
payout.refunded
total_debited_usd) have been credited back to the balance that paid the payout (Payout SEPA, or Ops Others for ACH). failure_reason names that balance. Status refunded, refunded_at is set. This is also the case when the amount received of a renewed quote would be more than 1% lower than the quote you accepted.Balance events
balance.deposit_confirmed
balance.deposit_confirmed
source field is only present for gift card redemptions. A gift card is issued for one specific ops balance and always credits that balance. gross_amount is the gift card value, fee the top-up fee of that balance and amount the net amount credited.balance.debited
balance.debited
reason values:brand, customer_code, product, billing_cycle) vary depending on the reason.balance.low_balance
balance.low_balance
lowBalanceThreshold, default $100). This is triggered in two ways:- Real-time — immediately after a debit that pushes the balance below the threshold
- Scheduled — every 4 hours, a CRON job checks all active partners
Signature verification
Every delivery includes these headers:Extract the timestamp and signature
X-KemyCard-Signature: split by ,, extract t= and v1= values.Compute expected signature
{timestamp}.{raw_body} and compute HMAC-SHA256 using your webhook secret.Compare signatures
crypto.timingSafeEqual in Node.js, hash_equals in PHP).Reject old timestamps
Retry policy
If your endpoint doesn’t respond with a2xx status code, we retry with exponential backoff:
failed and no further retries are made.
Managing endpoints
The number of active endpoints depends on your plan: 1 on Découverte, 10 on Starter, Business and Premium. Creating an endpoint beyond this number returns403 PLAN_LIMIT_REACHED. If your account returns to Découverte, your endpoints are kept but only the oldest one keeps working.
Update an endpoint
2xx.Disable / re-enable an endpoint
Rotate the secret
If your secret is compromised, generate a new one immediately:Test your endpoint
Send a manual ping to verify your endpoint is working:View delivery history
Check the delivery status for a specific endpoint:delivered/failed/pending), HTTP response code, attempt number, duration, and idempotency key.
Best practices
Always verify signatures
Always verify signatures
Use idempotency keys
Use idempotency keys
X-KemyCard-Idempotency-Key header value and check it before processing. Due to retries, you may receive the same event multiple times. Idempotency keys let you safely deduplicate.Return 200 quickly
Return 200 quickly
200 response immediately, then handle the event in a background job. If your endpoint takes too long (>10 seconds), the request will time out and trigger a retry.Subscribe only to events you need
Subscribe only to events you need
"*" unless you truly need every event. Subscribing to specific events reduces noise and unnecessary load on your server.Monitor your delivery history
Monitor your delivery history
Handle secret rotation gracefully
Handle secret rotation gracefully