Webhooks

Webhooks are how Versa clients consume asynchronous events. Receivers use webhooks to be notified of new encrypted data and customer lifecycle events, and senders use webhooks to track the progress of receipt retrievals they have requested.

Supported Events

Receiver events

Event	Description
receipt	The original encrypted payload. Existing senders use this event at the protocol level.
receipt.decrypted	The event received by custodial clients at their remote endpoint.
itinerary	The encrypted payload for an itinerary event, which excludes payment data.
itinerary.decrypted	As above, the custodial event for itineraries.

Sender events

These events correspond to the lifecycle of a receipt retrieval requested via the Receipt Retrieval API.

Event	Description
receipt_retrieval.scheduled	A receipt retrieval process has been scheduled for a transaction.
receipt_retrieval.initiated	A receipt retrieval has started running for a transaction.
receipt_retrieval.completed	A receipt was successfully attached to the transaction.
receipt_retrieval.failed	The receipt retrieval process for a transaction concluded unsuccessfully and will not be automatically retried.

Using Webhooks

On the Versa network, receipt data is sent directly from verified merchants to receivers. That means that the receipt event is posted to receivers by sending clients, not by the Versa registry. All receivers use webhooks to handle encrypted data sent over the protocol, and custodial clients use separate webhooks to get deliveries from Versa servers.

Custodial Webhooks

Custodial clients subscribe to a receipt.decrypted event. The custodial service receives and decrypts data on your behalf, and then posts a separate webhook event to your remote endpoint, in the following format:

{
  "event": "receipt.decrypted",
  "event_id": "evt_6abf1062dc2f4844a81b645b9a5dbf41",
  "event_at": 1739315358,
  "delivery_id": "whd_809aba728d6940de8e294af8b3ad272c",
  "delivery_at": 1739315358,
  "data": {
    "receipt": { ... },
    "checkout": {
      "sender": {
        "brand_color": "#f0C14B",
        "logo": "https://imagedelivery.net/image_url.png",
        "name": "Supplier Co.",
        "org_id": "org_b6d073a9bf3a4c49a8c03191f87d8ee2",
        "website": "supplier.com"
      },
      "handles": {
        "customer_email": "john.smith@example.com", 
        "customer_email_domain": "example.com"
      },
      "receipt_id": "rct_14a9817fea7d41bf941c16b8750cc845",
      "registered_at": 1739315357,
      "schema_version": "2.3.0",
      "transaction_id": "txn_6b408ba7406b4754b7b7d287e0ca9fdf",
      "transaction_event_index": 0
    }
  }
}

Receipt Retrieval Events

Senders who use the Receipt Retrieval API can subscribe to receipt retrieval events to track the progress of each attempted retrieval. Every event in this family carries the card_transaction_id and retrieval_id associated with the original request.

The receipt_retrieval.scheduled, receipt_retrieval.initiated, and receipt_retrieval.failed events share the following shape:

{
  "event": "receipt_retrieval.scheduled",
  "event_id": "evt_6abf1062dc2f4844a81b645b9a5dbf41",
  "event_at": 1739315358,
  "delivery_id": "whd_809aba728d6940de8e294af8b3ad272c",
  "delivery_at": 1739315358,
  "data": {
    "merchant_transaction_id": "your_booking_id"
  }
}

The receipt_retrieval.completed event additionally includes a URL to the retrieved file:

{
  "event": "receipt_retrieval.completed",
  "event_id": "evt_6abf1062dc2f4844a81b645b9a5dbf41",
  "event_at": 1739315358,
  "delivery_id": "whd_809aba728d6940de8e294af8b3ad272c",
  "delivery_at": 1739315358,
  "data": {
    "merchant_transaction_id": "your_booking_id",
    "receipt_file_url": "https://storage.googleapis.com/..."
  }
}

API Reference

You can create, list, update, and delete your webhooks, and you can rotate your webhook secrets at any time (remember to then update your destination endpoint with the new secret).

All webhook endpoints require Basic Authentication with your client credentials.

• POST /webhook - Create a new webhook
• GET /webhook - List all webhooks for your client
• PUT /webhook/:id - Update the endpoint_url or events for a specific webhook
• PUT /webhook/:id/rotate - Rotate the secret for a specific webhook
• DELETE /webhook/:id - Delete a specific webhook