Webhooks
Inbound webhooks for plugins, outside operator auth: the URL token is the credential.
Back to the web API reference.
Stores one inbound webhook request for a plugin instance.
The token is the credential; a row with a signing rule also needs a valid signature. The reply body never says more than the status.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
tokenpathstringrequiredThe webhook's URL token: 43 characters of base64url, from the plugin'sWEBHOOKS.url.namepathstringrequiredThe[[webhooks]]row's name.
The request body, kept as sent, at most the row's max_body_bytes.
*/*: BinaryBody
- 204Stored; the plugin reads it on its next pull. No body.
-
400A kept header repeats, is too long or holds a control character. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
401The signature is missing or does not match. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404The token or name matches no webhook. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
413The body is larger than the row allows. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
429The webhook is over its
rate_per_minute. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
503The webhook cannot take requests now: webhooks are off, the signing secret is not set, this node does not run the instance, the library is unavailable, or the instance already holds its cap of waiting requests. Retry later. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
$ curl 'http://127.0.0.1:8787/hooks/<token>/<name>' \
-X POST \
-H 'Content-Type: */*' \
--data-binary @file
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/hooks/<token>/<name>' `
-Method Post `
-ContentType '*/*' `
-InFile 'file'
import requests
response = requests.post(
"http://127.0.0.1:8787/hooks/<token>/<name>",
headers={"Content-Type": "*/*"},
data=open("file", "rb"),
)
print(response.status_code, response.text)
import { readFile } from "node:fs/promises";
const response = await fetch("http://127.0.0.1:8787/hooks/<token>/<name>", {
method: "POST",
headers: { "Content-Type": "*/*" },
body: await readFile("file"),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/hooks/<token>/<name>")
.header("Content-Type", "*/*")
.body(std::fs::read("file")?)
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 204: Stored; the plugin reads it on its next pull. No body.
Status 400: A kept header repeats, is too long or holds a control character.
{
"error": "bad_request",
"message": "The request could not be understood.",
"status": 400
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 401: The signature is missing or does not match.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 404: The token or name matches no webhook.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 413: The body is larger than the row allows.
{
"error": "payload_too_large",
"message": "Payload Too Large",
"status": 413
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 429: The webhook is over its rate_per_minute.
{
"error": "too_many_requests",
"message": "Too many requests. Try again shortly.",
"status": 429
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 503: The webhook cannot take requests now: webhooks are off, the signing secret is not set, this node does not run the instance, the library is unavailable, or the instance already holds its cap of waiting requests. Retry later.
{
"error": "service_unavailable",
"message": "The Bookclerk daemon is not ready to handle this request.",
"status": 503
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Generated from crates/bookclerkd/openapi.json at main · View as Markdown