Skip to main content

Webhooks

A webhook lets a query notify another system over HTTP when it runs. Kvery sends an HTTP POST to a URL you choose — on success, on failure, or both — without any backend code on your side. Webhooks are driven entirely by directives in your SQL.

Firing on success​

Use ON SUCCESS POST to notify a system after the query completes successfully:

INSERT INTO orders (customer_id, total)
VALUES (:customer_id, :total);
ON SUCCESS POST 'text, json' TO 'https://hooks.example.com/order-created'

When the INSERT succeeds, Kvery sends a POST to the URL with the payload you specify.

Firing on error​

Use ON ERROR POST to send an alert when the query fails — perfect for monitoring:

SELECT * FROM critical_report;
ON ERROR POST 'text, json' TO 'https://hooks.example.com/report-failed'

Using both together​

A single query can notify different endpoints for success and failure:

UPDATE invoices SET paid = 1 WHERE id = :id;
ON SUCCESS POST 'text, json' TO 'https://hooks.example.com/invoice-paid'
ON ERROR   POST 'text, json' TO 'https://hooks.example.com/invoice-error'

The payload​

The text/JSON you place between the quotes is sent as the body of the request. Keep it as JSON the receiving service can parse, and point the URL at any endpoint that accepts an inbound webhook (an automation tool, a chat notifier, your own API).

Choosing the HTTP method​

POST is the typical choice, but the method right after ON SUCCESS / ON ERROR can be any of GET, POST, PUT, PATCH or DELETE — use whatever the receiving endpoint expects:

UPDATE invoices SET paid = 1 WHERE id = :id;
ON SUCCESS PUT 'text, json' TO 'https://hooks.example.com/invoice/:id'

Common patterns​

  • Chained workflows — trigger a downstream job after a write completes.
  • Alerting — ON ERROR POST to a monitoring or chat endpoint.
  • Audit/notify — ON SUCCESS POST to record that a sensitive query ran.

Tips​

  • Combine webhooks with SET HTTPCODE and ON ERROR RETURN so the caller of your API and the webhook receiver both get clean, intentional responses.
  • Make sure the target URL is reachable from the internet and responds quickly.
  • See Posting data for the write queries these webhooks usually accompany.