WebhookEvent

A webhook lets an external system push data into your bot over plain HTTP. The server converts the incoming HTTP request into a WebhookEvent message and delivers it to your bot on its WebSocket session.

This is the only inbound path that does not originate from a nandbox user action — it is intended for integrating third-party systems (payment gateways, CRMs, order systems, CI pipelines) with your bot.

How it works

An external system sends an HTTP POST with a JSON body to your bot's callback URL.

The server parses the body as JSON.

The server adds "method": "WebhookEvent" to that object.

The whole object is delivered to your bot over its WebSocket session.

The server replies to the HTTP caller with 200 OK and the plain-text body ok.

The payload is passed through untouched — the server does not validate, reshape, or filter it beyond adding method.

Callback URL

plain text
POST https://<nandboxBotServer>:<port>/api/callback/<botId>
Content-Type: application/json

<botId> is your bot's numeric id — the value returned as ID in the TOKEN_AUTH_OK response.

Event received by the bot

Field	Type	Returned	Description
`method`	String	Yes	`"WebhookEvent"`. Added by the server.
`ref`	String	Optional	Correlation id, only if the caller included a `ref` key in the posted body.
`app_id`	String	Optional	Only if the caller included an `app_id` key in the posted body.
(all other keys)	Any	Conditional	Every remaining key of the posted body, passed through unchanged. The SDKs expose these together as the body.

The SDKs lift ref, app_id and method out of the payload and expose everything that remains as body.

Preconditions for API Functionality

The following tables outline the preconditions that must be met for the API to function correctly. Failure to meet these conditions may result in errors or unexpected behavior.

Action	Requirement	Description
Receive webhook	Authenticated session	The bot must be connected and authenticated, so the server has a live WebSocket session to deliver the event on.
Receive webhook	Valid JSON body	The posted body must parse as a JSON object. Malformed payloads are discarded.

⚠️ Security — the callback endpoint does not authenticate the caller. Anyone who knows your bot id can deliver a WebhookEvent to your bot. Treat every event as untrusted input: include a shared secret in the posted body and verify it in your bot before acting on the event.

SDK Mapping — `WebhookEvent`

SDK	Response Callback	Accessors
Java	`onWebhookEvent(WebhookBody webhookEvent)`	`getRef()`, `getAppId()`, `getMethod()`, `getBody()`
JavaScript	`onWebhookEvent(webhookEvent)`	`.ref`, `.appId`, `.method`, `.body`
Python	`on_webhook_event(self, webhook_event)`	`.ref`, `.app_id`, `.method`, `.body`

Example

Incoming HTTP request

plain text
curl -X POST "https://<nandboxBotServer>:<port>/api/callback/90091784056528980" \
  -H "Content-Type: application/json" \
  -d '{"ref":"inv-1042","secret":"s3cr3t","event":"invoice.paid","amount":250}'

Event delivered to the bot

json
{
  "method": "WebhookEvent",
  "ref": "inv-1042",
  "secret": "s3cr3t",
  "event": "invoice.paid",
  "amount": 250
}

The bot sees ref = "inv-1042" and a body of {"secret":"s3cr3t","event":"invoice.paid","amount":250}.

Handling the event

java
@Override
public void onWebhookEvent(WebhookBody webhookEvent) {
    JSONObject body = webhookEvent.getBody();
    if (!"s3cr3t".equals(body.get("secret"))) {
        return; // reject unauthenticated callers
    }
    System.out.println("ref: " + webhookEvent.getRef());
    System.out.println("event: " + body.get("event"));
}

javascript
nCallBack.onWebhookEvent = (webhookEvent) => {
    const body = webhookEvent.body;
    if (body.secret !== "s3cr3t") return; // reject unauthenticated callers
    console.log("ref:", webhookEvent.ref);
    console.log("event:", body.event);
}

python
class nCallBack(nandbox.Callback):
    def on_webhook_event(self, webhook_event):
        body = webhook_event.body
        if body.get("secret") != "s3cr3t":
            return  # reject unauthenticated callers
        print("ref:", webhook_event.ref)
        print("event:", body.get("event"))