Webhooks

Set up an endpoint

Event catalog

The payload

{
  "id": "8f3b2c1a-...",              // unique id of this delivery (= webhook-id header)
  "type": "payment.credited",
  "event_at": "2026-07-22T14:47:38.609Z",  // when the event happened: shortly after credited_at (equal to it on a recovered notice)
  "data": {
    "payment": {
      "uuid": "f893...",            // stable payment id (use it to correlate)
      "folio": "PAY-00000002",
      "status": "credited",         // credited | failed | pending
      "amount_cents": 15000,        // money is ALWAYS in cents + currency
      "credited_amount_cents": 15000,
      "currency": "MXN",
      "provider": "manual",         // manual | stripe | mercadopago | paypal
      "method": null,               // informational (card | spei | paypal | ...); never "manual"
      "bank": null,                 // bank (SPEI-push); null for manual and card
      "bank_account": "BANORTE0876", // manual only: the account the money went into
      "bank_datetime": "2026-07-22T14:47:00Z", // manual only, optional
      "files": [                    // receipts (manual only); [] if none
        { "uuid": "92c9...", "name": "receipt.pdf", "mime_type": "application/pdf" }
      ],
      "transaction_id": null,       // online: provider id; manual: bank id captured when crediting (null if not captured)
      "receipt_url": null,          // null for manual; receipt page for credited online
      "fail_reason": null,          // only set on payment.failed: the FREE-TEXT reason your team wrote
      "credited_at": "2026-07-22T14:47:38.204Z",
      "description": "Partial payment for order 4471",  // payment note written by your team or your AI employee; null if none
      "custom_fields": {                                // the custom fields you defined; {} if there are none
        "Payment type": "Installment",
        "Order": "4471"
      }
    },
    "conversation_info": {
      "uuid": "c9ba...",            // null if the conversation was deleted
      "phone": "529671941293",
      "inbox_status": "pending",
      "is_tester": false,           // false on these webhooks: they never emit test payments
      "mailbox": { "name": "Sales" }
    },
    "contact_info": {
      "first_name": "Maikol",
      "middle_name": null,
      "last_name": null,
      "second_last_name": null,
      "full_name": "Maikol",
      "username": null,             // WhatsApp handle (without "@"), if known
      "phone": "529671941293",
      "whatsapp_user_id": "MX.1343..." // WhatsApp identity (or the phone if there is no BSUID yet)
    }
  }
}

description and custom_fields: the context your team writes

• description is the payment note. Whoever registers the payment writes it from the panel, or your AI employee drafts it if you configured a guide for that. It is free prose: null when nobody wrote anything.
• custom_fields are the custom fields you defined in your account —“Payment type”, “Order”, whichever you need— with the value captured on that payment. While the field is rolling out in stages the key may not be there at all; when it is, it’s always an object: {} when none were captured.

If you receive events through two channels, deduplicate by payment.uuid

What your endpoint answers can continue the conversation

• Your response body is shown to a model. Only return what you are fine with the customer eventually learning: no credentials, no other customer’s data, no internal dumps. If it is long, it gets truncated. Before showing it we mask the values of credential-named fields (token, password, api_key…), 18-digit numbers —even when split by spaces or hyphens— and the /pay/… part of links, so if your response carries a CLABE or a link with /pay/…, the AI will not be able to pass it on to the customer. That filter is a safety net, not a guarantee: it does not recognize every field name, nor payment links from other gateways, so do not send credentials or bank details relying on it.
• It is only read if you answer 2xx and with a body, and even then it is not guaranteed. An error or an empty response continues nothing, and that dispatch is not repeated if you answer 4xx or 5xx. It is repeated once only if you do not answer within 30 seconds or the connection fails, so it can reach you twice and with no idempotency key: this dispatch carries no webhook-id and no signature, so deduplicating is on you. The retries, the timeout and the webhook-id in Delivery and retries belong only to the payment event webhooks. It does continue even if at that moment a person is handling the conversation or it is pending. There is no guaranteed timeframe between your response and the message to the customer.
• The chain has a cap, and it depends on where the dispatch came from. If the continuation dispatches to your URL again, that response can continue the conversation too, up to the cap:
  • Up to two continuations when the dispatch comes from what opens the turn: the JSON employee running on its own —the assigned one, or one launched directly from the panel, a campaign or this API—, a standalone send_json action in an action group, or the action set of the employee answering a customer message, a scheduled message or the “Run” button on the assigned employee (with its own send_json or a JSON employee that set launches).
  • Only one when the action set of an employee that something else launched dispatches: another action set, this API (run_ai, ai_assistance, assign_ai_employee with run: true or Smart Actions), a campaign, or “Run” on an employee that isn’t the assigned one. A JSON employee that set launches also stays at one.
  The cap is per chain, not per conversation: every customer message starts it over.
• A campaign dispatches to you once per recipient. If the business team puts a send_json or a JSON employee in a campaign, you get one request per recipient, and with the processing configured each response can continue its conversation. A send_json placed before the campaign’s first AI action goes out at the send’s pace. If it comes after, it goes out from a queue that caps how many start at once per business, but not how many are still running: a slow one can free its place before it finishes. There is no guaranteed pace. Size your endpoint for the size of the audience, not for that of a single conversation.
• It does not apply to dispatches that carry the payment field, even if it holds no payment (an empty array, or an object with an empty data). There the response is not read, by design: an endpoint that echoes the request would return bank details, and the cutoff does not tell a field without payments from one with payments.

fail_reason: free text written by a person

Headers on every delivery

Verify the signature

import { Webhook } from "standardwebhooks";

// whsec_… stored in an environment variable
const wh = new Webhook(process.env.WEBHOOK_SECRET);

// rawBody = the request's raw body (string), NOT the already-parsed object
const payload = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});
// If the signature doesn't validate, verify() throws — respond 400 and don't process.

import os
from standardwebhooks import Webhook

wh = Webhook(os.environ["WEBHOOK_SECRET"])

# raw_body = the request's raw body (bytes/str), NOT the already-parsed dict
payload = wh.verify(raw_body, {
    "webhook-id": headers["webhook-id"],
    "webhook-timestamp": headers["webhook-timestamp"],
    "webhook-signature": headers["webhook-signature"],
})
# If the signature doesn't validate, verify() throws — respond 400 and don't process.

import crypto from "crypto";

function verifyWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];

  // Reject replays outside ±5 min (the webhook-timestamp is part of the signature).
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > 300) return false;

  const signedContent = `${id}.${ts}.${rawBody}`;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(signedContent).digest("base64");

  // The header may carry several signatures (rotation), space-separated.
  const received = headers["webhook-signature"]
    .split(" ")
    .map((s) => s.replace(/^v1,/, ""));

  return received.some((sig) => {
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

import base64, hashlib, hmac, time

def verify_webhook(raw_body: str, headers: dict, secret: str) -> bool:
    # Reject replays outside ±5 min (the webhook-timestamp is part of the signature).
    if abs(int(time.time()) - int(headers["webhook-timestamp"])) > 300:
        return False

    signed_content = f'{headers["webhook-id"]}.{headers["webhook-timestamp"]}.{raw_body}'

    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(
        hmac.new(key, signed_content.encode(), hashlib.sha256).digest()
    ).decode()

    # The header may carry several signatures (rotation), space-separated.
    received = [s.removeprefix("v1,") for s in headers["webhook-signature"].split(" ")]
    return any(hmac.compare_digest(sig, expected) for sig in received)

Delivery and retries

Rotate the secret

Receipts

curl "https://app.1to1ai.com/api/v1/public/{slug}/payments/{paymentUuid}/files/{fileUuid}" \
  -H "Authorization: Bearer sk_1to1_your_api_key"

{
  "download_url": "https://...",
  "expires_at": "2026-07-22T15:17:38.609Z"
}

Next steps