Response Modes: Streaming vs. Buffered

Webhookd offers different modes for how it sends the script's output back to the client. This allows you to choose between getting real-time feedback or a consolidated response after the script completes.

The mode can be controlled per-request via the X-Hook-Mode header or globally via the WHD_HOOK_DEFAULT_MODE configuration.

Chunked Mode (Default)

In chunked mode, Webhookd uses Chunked Transfer Encoding to stream the script's output (stdout and stderr) to the client as it's generated. This is the default behavior and is ideal for long-running processes where you want to monitor progress in real-time.

  • How to use: Send the request with X-Hook-Mode: chunked or no mode header at all.
  • Response: The HTTP response body will contain the raw output from the script, sent in chunks.

Example: 

curl -XPOST --header "X-Hook-Mode: chunked" http://localhost:8080/path/to/script
# --- Immediate Response --- 
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
X-Hook-Id: 7

# --- Streamed Body --- 
First line of output...
(wait for script execution)
Second line of output...
error: exit status 0

Server-Sent Events (SSE) Mode

This mode is a specialized form of streaming that conforms to the Server-Sent Events standard. It's particularly useful for web front-ends that need to consume the log stream easily using the EventSource API.

  • How to use: Set the Accept header to text/event-stream.
  • Response: Each line of output from the script is prefixed with data:.

Example: 

curl --header "Accept: text/event-stream" http://localhost:8080/path/to/script
# --- Immediate Response --- 
HTTP/1.1 200 OK
Content-Type: text/event-stream
Transfer-Encoding: chunked
X-Hook-Id: 8

# --- Streamed Body (SSE format) --- 
data: First line of output...

data: Second line of output...

error: exit status 118

Buffered Mode

In buffered mode, Webhookd waits for the script to finish executing completely before sending a response. The response body will contain a limited number of the last lines of the script's output.

This mode is useful when you only care about the final result and don't need real-time progress.

  • How to use: Send the request with X-Hook-Mode: buffered.
  • Response: The HTTP response is blocked until the script completes. The response body contains the final output (truncated), and the HTTP status code reflects the script's exit code.

Exit Code to HTTP Status Code Mapping:

  • exit 0: Returns HTTP 200 OK.
  • exit 1-99: Returns HTTP 500 Internal Server Error.
  • exit 100-255: Returns HTTP status (exit code + 300). For example, exit 118 becomes HTTP 418 I'm a teapot.

Example:

Consider a script that exits with code 118: 

#!/bin/bash
echo "foo foo foo"
echo "bar bar bar"
exit 118

Request: 

curl -v --header "X-Hook-Mode: buffered" http://localhost:8080/path/to/script

Response: 

< HTTP/1.1 418 I'm a teapot
< Content-Type: text/plain; charset=utf-8
< X-Hook-Id: 9

foo foo foo
bar bar bar
error: exit status 118