Developer guide

Webhooks and channels

3 min read

Webhooks communicate durable Operation and reconciliation state changes. Delivery may be repeated, so the Partner verifies signature/freshness and deduplicates by event/delivery ID. A webhook failure does not revert a transaction that already finalized.

Partner-app state projection

B2B event → signed webhook → Partner backend → state projection → Partner app

If delivery is delayed, GET Operation and event cursors allow the Partner to rebuild authoritative state.

WhatsApp-first

flowchart LR
    U[Partner user] -->|1| WA[Partner number/WABA]
    WA -->|2| BOT[Partner Chatizalo instance]
    BOT -->|3| API[B2B API]
    API -->|4| OP[Operation]
    OP -->|5| SG[Partner signer]
    OP -->|6| CH[Blockchain]
    OP -->|7| WH[Partner webhook]
    OP -->|8| BOT
    BOT -->|9| U

What each step does

  1. Partner user → Partner number/WABA. The conversation happens on the Partner's own WhatsApp number. The number, the credentials, the templates and the tenant belong to the Partner.
  2. Number/WABA → Partner Chatizalo instance. The inbound message reaches the conversational instance, which reads the intent and collects whatever is missing.
  3. Chatizalo instance → B2B API. The instance resolves the recipient, asks for a quote and, after the explicit confirmation, creates the operation with an idempotency key and the evidence of the channel.
  4. B2B API → Operation. The API checks that the sender is linked to an enabled TenantUser, applies the tenant's limits and policy, and persists the operation. A phone number works as an alias of the channel, and the authority to spend comes from that link.
  5. Operation → Partner signer. The signature is requested under the policy of the tenant.
  6. Operation → Blockchain. The adapter broadcasts, and the observers follow the evidence on chain.
  7. Operation → Partner webhook. The durable event reaches the Partner's backend, signed, so the Partner keeps its own projection of what happened.
  8. Operation → Chatizalo instance. The state of the operation returns to the conversation.
  9. Chatizalo instance → Partner user. The person reads the result in the same thread where they asked for it.

Each Partner may have isolated channel credentials, prompts, templates and configuration. The channel never signs or writes ledger postings directly.

Authorization is a separate policy dimension: direct WhatsApp confirmation may be enough for a permitted low-risk operation, while another policy can require Partner callback, signed grant or app step-up.

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

  • Cursor events and signed webhooks — Every state change of an operation produces an event. The Partner reads them from a cursor, or receives them as HTTP calls signed with its secret so it can check that they come from the platform.

  • End-to-end webhook delivery — Deliveries are proven against a receiver that verifies the signature, keeps the valid ones and rejects the rest, with the result of each attempt recorded.

  • Chatizalo outbound adapter — When an operation is started from a conversation, the result is sent back through the same channel to the same user, so whoever asked for the transfer gets the answer where they asked for it.

  • Durable outbox, retry and notification DLQ — The event is written to the database before delivery is attempted. If the destination fails, it is retried with increasing waits, and after the last attempt it is left in a separate queue for review.

  • Inbound WhatsApp with human confirmation — A person starts an operation from a conversation, receives the quote with the amount and the fee, and confirms it in an explicit message before anything executes. The sender's identity comes from the channel.

  • WebSocket and Telegram — Two more channels for receiving requests and sending back results, under the same limits, the same policy and the same confirmation as WhatsApp.