Webhook Setup

Webhooks are how OpenCard talks to your app. Every transaction, receipt, and lifecycle event gets POSTed to your URL.

Create webhook

POST /accounts/{accountId}/organizations/{organizationId}/webhooks
Scope: webhooks-write

{
  "url": "https://your-app.com/hooks/opencard",
  "enabled": true,
  "authentication_type": "basic",
  "basic_username": "opencard",
  "basic_password": "your-secret-password",

  "card_transaction_authorized": true,
  "card_transaction_cleared": true,
  "card_transaction_deleted": true,
  "card_transaction_invoiced": false,
  "card_holder_created": true,
  "card_holder_identified": true,
  "card_holder_signed_pdpc": true,
  "card_holder_deleted": true,
  "receipt_fetched": true,
  "transaction_true_vat": true,
  "transaction_line_items": true,
  "tpa_signed": true
}

Field	Notes
`url`	Your HTTPS endpoint. Must be reachable from internet.
`secret`	Auto-generated 60-char string if omitted. Used for challenge HMAC.
`enabled`	`true` to activate (after challenge passes)
`authentication_type`	`none`, `basic`, `oauth`, or `custom`
Event flags	Boolean per event type. Only subscribed events are delivered.

Response includes secret — save it. You need it for challenge verification.

Challenge handshake 🔐

Immediately after create (or URL change), OpenCard verifies you own the endpoint:

GET https://your-app.com/hooks/opencard?challenge=RANDOM_20_CHAR_STRING
Header: X-Event: challenge

Your server must respond 200 with header:

X-Verify-Token: HMAC-SHA256(challenge_string, webhook_secret)

Node.js example:

const crypto = require('crypto');

app.get('/hooks/opencard', (req, res) => {
  const challenge = req.query.challenge;
  if (!challenge) return res.status(400).send('missing challenge');

  const token = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(challenge)
    .digest('hex');

  res.set('X-Verify-Token', token).status(200).send('ok');
});

If HMAC matches → active=true. If not → active=false, no events delivered.

Receiving events

Events come as POST to your URL:

POST https://your-app.com/hooks/opencard
X-Event: card.transaction.authorized
Content-Type: application/json

{ ... payload ... }

Plus auth headers if configured:

`authentication_type`	What OpenCard sends
`none`	Just `X-Event`
`basic`	`Authorization: Basic base64(user:pass)`
`custom`	Your `custom_key: custom_value` as HTTP header
`oauth`	Bearer token fetched from your `oauth_access_token_url`

Always respond 200 quickly. Process async if needed. OpenCard retries on failure.

Custom headers

Add extra headers OpenCard includes on every delivery:

POST .../webhooks/{webhookId}/headers
{ "key": "X-My-App-Id", "value": "ems-prod-001" }

Webhook groups (buyer-party filter)

Filter events by card issuer buyer party:

POST .../webhooks/{webhookId}/groups
{ "buyer_party": "5561234567" }

Only transactions matching that buyer party hit this webhook.

Test an event

POST .../webhooks/{webhookId}/test/card.transaction.authorized

Sends a test payload to your endpoint. Good for verifying your handler works.

Delivery log

GET .../webhooks/{webhookId}/events
Scope: webhook-events-read

Paginated log of every delivery attempt — status code, payload, timestamp. Use for debugging.

Checklist ✅

HTTPS endpoint deployed
Challenge handler implemented (GET with ?challenge=)
Event handler implemented (POST with X-Event header)
Respond 200 fast, process async
secret stored securely
Subscribed to the right event flags
Test event sent and received

EMS Integration

Customer onboarding

Model

Platform

Webhooks

Enrichment

Advanced

API — Auth

API — Endpoints

Create webhook

Challenge handshake 🔐

Receiving events

Custom headers

Webhook groups (buyer-party filter)

Test an event

Delivery log

Checklist ✅

​Create webhook

​Challenge handshake 🔐

​Receiving events

​Custom headers

​Webhook groups (buyer-party filter)

​Test an event

​Delivery log

​Checklist ✅

Create webhook

Challenge handshake 🔐

Receiving events

Custom headers

Webhook groups (buyer-party filter)

Test an event

Delivery log

Checklist ✅