Webhook

When the sketch virtualWrites this pin, the Box IO server calls a URL. Dashboard edits do not fire it. Comma-separated fields fill the data template.

Sample pin: V11

Set it up on the server

1. Sign in to the Box IO dashboard and open the project that uses this device key.
2. Turn on Edit.
3. In Edit, add Webhook.
4. Set Virtual pin to 11. The device on the widget, or the project device, must be the device key in the sketch.
5. Set URL to an http or https address. The server must be able to reach it.
6. Set Method to GET, POST, or PUT.
7. Set Content type to one of application/json, text/plain, or application/x-www-form-urlencoded.
8. Set Data using {1}, {2}, {3}, and {value}. Three variables go out in one comma-separated virtualWrite.
9. Save the layout. The call happens only after a device virtualWrite. The widget shows the pin value and a status such as 204 POST.
10. Hide on the widget, or Hide in live in the properties, removes it from the Live view. Edit still shows it. The URL is still called. Save the layout to keep the choice.
11. Flash the sketch below with the same device key, host, and port 5923. Keep BoxIO.run() in loop().

Properties

Sketch values are always strings, including numbers: BoxIO.setProperty(V2, "max", "200").

Formatting

• BoxIO.virtualWrite(V11, "72,north room") makes {1} = 72 and {2} = north room.
• Three variables use the same comma split. Keep commas out of the values, because a comma starts the next field. Spaces around commas are trimmed.
• Example 1, mixed numbers and text: char payload[96]; snprintf(payload, sizeof(payload), "%d,%s,%s", temp, room, status); BoxIO.virtualWrite(V11, payload); Writing 72,north room,ok makes {1} = 72, {2} = north room, and {3} = ok. JSON Data {"temp":"{1}","room":"{2}","status":"{3}"} is sent as {"temp":"72","room":"north room","status":"ok"}. Form Data temp={1}&room={2}&status={3} is sent as temp=72&room=north+room&status=ok.
• Example 2, three integers: int values[] = {temp, humidity, pressure}; BoxIO.virtualWrite(V11, values, 3); A float array is joined the same way. Each float is written with two decimal places.
• application/json escapes quotes, backslashes, and newlines inside each inserted value. Template {"temp":"{1}","room":"{2}"} is sent as {"temp":"72","room":"north room"}. A room named north "hall" does not break the JSON.
• application/x-www-form-urlencoded encodes each inserted value. Spaces become +. & and = become %26 and %3D. Template temp={1}&room={2} is sent as temp=72&room=north+room.
• text/plain inserts the values unchanged. The header is text/plain;charset=utf-8.
• GET appends Data with ? or &. A form content type still uses + for spaces on that query. POST and PUT send the body with the Content-Type you picked.
• If Content type is left empty, a template that starts with { or [ is JSON, a template that contains = is form data, and anything else is plain text.
• Only http and https are called. The request times out after 8 seconds. The status line is stored on the pin as webhookStatus.

Sketch

Paste the device key over bx_paste_your_device_key_here. Wi-Fi boards include BoxIOEsp32.h. Ethernet boards use the same calls with an EthernetClient.

#define BOXIO_AUTH "bx_paste_your_device_key_here"
#define WIFI_SSID  "your-ssid"
#define WIFI_PASS  "your-password"
#define BOXIO_HOST "localhost"
#define BOXIO_PORT 5923

#include <BoxIOEsp32.h>

void setup() {
  BoxIO.begin(BOXIO_AUTH, WIFI_SSID, WIFI_PASS, BOXIO_HOST, BOXIO_PORT);
// JSON Data:
  // {"temp":"{1}","room":"{2}","status":"{3}"}
  // Form Data:
  // temp={1}&room={2}&status={3}
}

void loop() {
  BoxIO.run();
static uint32_t last = 0;
  if (millis() - last < 5000) return;
  last = millis();

  // Example 1. Mixed numbers and text.
  // {1} = 72, {2} = north room, {3} = ok.
  int temp = 72;
  const char* room = "north room";
  const char* status = "ok";
  char payload[96];
  snprintf(payload, sizeof(payload), "%d,%s,%s", temp, room, status);
  BoxIO.virtualWrite(V11, payload);

  // Example 2. Three integers. The library joins them with commas.
  // Use this instead of Example 1 when every value is a number.
  // int humidity = 40;
  // int pressure = 1013;
  // int values[] = {temp, humidity, pressure};
  // BoxIO.virtualWrite(V11, values, 3);
}

What you should see

After the virtualWrite, the widget leaves “Waiting for virtualWrite” and shows 72,north room,ok plus the HTTP status. With the JSON template, the server posts {"temp":"72","room":"north room","status":"ok"}. A button click on a different widget does not call this URL. The call is only from virtualWrite on V11.