Webhooks

Webhooks are how receiver clients consume Versa events.

Supported 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.
customer.registered_by_sender	An event triggered to the receiver client upon sender registration.
customer.deregistered_by_sender	An event triggered to the receiver client upon sender deregistration.

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.1.0",
      "transaction_id": "txn_6b408ba7406b4754b7b7d287e0ca9fdf",
      "transaction_event_index": 0
    }
  }
}

Customer Events

The customer.registered_by_sender and customer.deregistered_by_sender events are sent to receivers when a sender registers or deregisters a customer, and take the following format:

{
  "event": "customer.registered_by_sender",
  "event_id": "evt_6abf1062dc2f4844a81b645b9a5dbf41",
  "event_at": 1739315358,
  "delivery_id": "whd_809aba728d6940de8e294af8b3ad272c",
  "delivery_at": 1739315358,
  "data": {
    "sender": { ... },
    "references": [
      {
        "handle": "example.com",
        "handle_type": "customer_email_domain"
      }
    ]
  }
}

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