betool betool

Documentation

HTTP Webhook

Generic reception of signed HTTP events from any system.

HTTP Webhook

The webhook channel is the generic entry point for connecting any system capable of making an HTTP POST. It is the option to choose when no dedicated channel exists for your source.

When to use it

  • Connect an in-house tool (ERP, business application, payment gateway).
  • Receive events from a third-party platform that offers webhooks (Stripe, Shopify, SendGrid…).
  • Trigger a pipeline from an external cron job or a CI pipeline.

Configuration

  1. Administration → Webhooks → New entry.
  2. Choose the target pipeline.
  3. betool generates a public URL (https://platform.betool.ai/entries/webhook/<id>) and an HMAC secret.

The secret is used to sign each payload: your system must compute HMAC-SHA256(secret, body) and pass it in the X-Betool-Signature header. Requests without a valid signature are rejected.

Payload format

You send any JSON you like. betool does not constrain the structure. The payload is exposed to the pipeline under webhook.payload (with its sub-keys).

Example:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Betool-Signature: $SIGNATURE" \
  -d '{
    "type": "order.created",
    "order_id": "ord_42",
    "amount_cents": 9900,
    "customer_email": "client@exemple.com"
  }'

The pipeline can then wire an agent that reads webhook.payload.customer_email and webhook.payload.amount_cents directly.

Response

By default, the HTTP response returns 202 Accepted immediately (pipeline launched in the background). If you need to wait for the pipeline result, configure the webhook in synchronous mode — the request blocks until the pipeline completes (30s timeout).

Security

  • Always sign your requests (HMAC).
  • The secret can be regenerated from the admin panel (rotation).
  • Payloads are stored in plain text in the execution history — do not send data that should be encrypted in transit only.