HTTP API Reference

This document details the HTTP endpoints provided by Webhookd.

Webhook Execution

This is the primary endpoint for triggering your scripts.

  • Endpoint: /<path>/<to>/<script>
  • Method: GET, POST, PUT, etc. (Any method is accepted)

Request Headers

The following headers can be used to control the behavior of the hook execution:

  • X-Hook-Mode: Specifies the response mode. See Response Modes for details.
  • chunked (Default): Streams the script output in real-time.
  • buffered: Waits for the script to finish and returns the last N lines of output.
  • Accept: text/event-stream: An alternative way to request a real-time stream using the Server-Sent Events (SSE) protocol.
  • X-Hook-Timeout: Overrides the global timeout for this specific request. The value is in seconds. (e.g., X-Hook-Timeout: 30)
  • X-Hook-MaxBufferedLines: When using buffered mode, this controls the maximum number of log lines to return in the response. Defaults to 100.

Response Headers

  • X-Hook-Id: A unique identifier for the hook execution. This ID can be used to retrieve logs later.

Status Codes

  • 200 OK: The script was accepted for execution. In streaming modes, this code is sent immediately. In buffered mode, it means the script finished with an exit code of 0.
  • 404 Not Found: The requested script could not be found.
  • 418 I'm a teapot (and other 4xx/5xx codes): In buffered mode, the script's exit code is mapped to an HTTP status code. The formula is exit_code + 300 for exit codes between 100 and 255. For codes 1-99, it returns 500 Internal Server Error.
  • 500 Internal Server Error: An internal error occurred in Webhookd, or the script exited with a code between 1 and 99 in buffered mode.

Log Retrieval

Retrieve the full output logs of a previously executed webhook.

  • Endpoint: /<path>/<to>/<script>/<ID>
  • Method: GET

URL Parameters

  • <ID>: The X-Hook-Id returned from the initial webhook execution.

Status Codes

  • 200 OK: Returns the full log output as text/plain.
  • 404 Not Found: The script or the log file for the specified ID could not be found.
  • 500 Internal Server Error: An error occurred while trying to read the log file.

Health Check

An unauthenticated endpoint to check the health of the Webhookd server.

  • Endpoint: /healthz
  • Method: GET

Status Codes

  • 204 No Content: The server is healthy and running.
  • 503 Service Unavailable: The server is in the process of shutting down.

Server Variables & Metrics

An endpoint to expose internal server metrics and variables, useful for monitoring.

  • Endpoint: /varz
  • Method: GET

Response

  • 200 OK: Returns a JSON object containing server statistics.

Example Response Body: 

{
"goroutines": 12,
"hookstats": {"requests": 5, "requests_failed": 1},
"uptime": 3600123456789
}

  • goroutines: Number of active Go routines.
  • hookstats: Metrics related to hook executions.
  • requests: Total number of requests processed.
  • requests_failed: Number of requests that resulted in an error.
  • uptime: Server uptime in nanoseconds.