webhook.h

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file webhook.h
 * @brief Outbound webhooks / IFTTT (DETWS_ENABLE_WEBHOOK).
 *
 * Builds an IFTTT Maker webhook URL and its value1/value2/value3 JSON payload
 * (pure, host-tested), and fires them - or any JSON to any URL - via the outbound
 * http_client (a POST). Lets the device push an event to IFTTT, a Slack/Discord
 * incoming webhook, or your own REST endpoint. Needs DETWS_ENABLE_HTTP_CLIENT to
 * send; without it the API still compiles but detws_webhook_post() returns -1.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef DETERMINISTICESPASYNCWEBSERVER_WEBHOOK_H
#define DETERMINISTICESPASYNCWEBSERVER_WEBHOOK_H
 
#include "ServerConfig.h"
#include <stddef.h>
 
#if DETWS_ENABLE_WEBHOOK
 
// ---------------------------------------------------------------------------
// Host-testable builders
// ---------------------------------------------------------------------------
 
/**
 * @brief Build the IFTTT Maker URL `https://maker.ifttt.com/trigger/<event>/with/key/<key>`.
 * @return characters written, or 0 if it would not fit @p cap (fail-closed).
 */
int detws_ifttt_url(const char *event, const char *key, char *out, size_t cap);
 
/**
 * @brief Build an IFTTT `{"value1":..,"value2":..,"value3":..}` JSON body.
 *
 * Null values are omitted; values are JSON-escaped for `"` and `\`. An all-null
 * call yields `{}`.
 * @return characters written, or 0 if it would not fit @p cap (fail-closed).
 */
int detws_ifttt_payload(const char *v1, const char *v2, const char *v3, char *out, size_t cap);
 
// ---------------------------------------------------------------------------
// Fire (ESP32 via http_client; HTTP_CLIENT_ERR_* on host)
// ---------------------------------------------------------------------------
 
/** @brief POST @p json (application/json) to @p url. @return HTTP status (>0) or negative error. */
int detws_webhook_post(const char *url, const char *json);
 
/**
 * @brief Trigger an IFTTT Maker event with up to three values.
 * @return HTTP status (>0) or a negative error (e.g. URL/payload build or transport).
 */
int detws_ifttt_trigger(const char *event, const char *key, const char *v1, const char *v2, const char *v3);
 
#endif // DETWS_ENABLE_WEBHOOK
#endif // DETERMINISTICESPASYNCWEBSERVER_WEBHOOK_H