Webhooks

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Inbound webhooks for plugins, outside operator auth: the URL token is the credential.

Back to the web API reference.

POST /hooks/{token}/{name}

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

Parameters

  • tokenpathstringrequiredThe webhook's URL token: 43 characters of base64url, from the plugin's WEBHOOKS.url.
  • namepathstringrequiredThe [[webhooks]] row's name.

Request body

The request body, kept as sent, at most the row's max_body_bytes.

*/*: BinaryBody

Responses

  • 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 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 401The signature is missing or does not match. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404The token or name matches no webhook. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 413The body is larger than the row allows. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 429The webhook is over its rate_per_minute. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable 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 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.

Example request

$ 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?);

Example response

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