Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt

Use this file to discover all available pages before exploring further.

Add a webhook endpoint to a store. Each store can have up to 20 webhooks across all channels. 
POST /v1/actions/store/add-webhook
Authentication: API Key (owner or admin role required)

​
Request Body

FieldTypeRequiredDescription
storeIdstringYesStore ID (Short ID format STO_xxx)
channelstringYesOne of http, feishu, discord, telegram, slack
urlstringYesTarget webhook URL (HTTPS; merchant ensures URL matches the chosen channel)
eventsstring[]YesSubscribed event types — e.g. ["order.completed", "refund.succeeded"]. Empty array means no events fire to this webhook.
testModebooleanYestrue = fires for test transactions; false = fires for production
secretstring | nullNoChannel-specific credential (e.g. Telegram chat_id). Stored as opaque text.

​
Example Request

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

// Standard HTTPS webhook (RSA-signed envelope)
const { webhook } = await client.webhooks.add({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  channel: "http",
  url: "https://example.com/webhooks/pancake",
  events: ["order.completed", "refund.succeeded"],
  testMode: false,
});

​
Success Response (200)

{
  "data": {
    "webhook": {
      "id": "11111111-2222-3333-4444-555555555555",
      "storeId": "uuid-of-store",
      "channel": "http",
      "url": "https://example.com/webhooks/pancake",
      "events": ["order.completed", "refund.succeeded"],
      "testMode": false,
      "secret": null,
      "createdAt": "2026-05-07T00:00:00.000Z",
      "updatedAt": "2026-05-07T00:00:00.000Z"
    }
  }
}
The returned webhook.id is a UUID, not a Short ID — webhook IDs are not in the IdPrefix scope. Pass it as-is to update-webhook and remove-webhook.

​
Response Fields

FieldTypeDescription
idstringWebhook UUID
storeIdstringOwning store UUID
channelstringWebhook channel (http, feishu, discord, telegram, or slack)
urlstringTarget webhook URL
eventsstring[]Subscribed event types
testModebooleantrue for test transactions, false for production
secretstring | nullChannel-specific credential (opaque text), null if unset
createdAtstringCreation timestamp (ISO 8601)
updatedAtstringLast update timestamp (ISO 8601)

​
Error Responses

StatusDescription
400channel not in the allowed list, url not a valid HTTPS URL, events not a string array, secret not string/null, or store already has 20 webhooks
403Caller is not an owner or admin of the store