Skip to API content
Birdor API v1

API reference · v1

Verify a webhook signature

Recompute the HMAC signature of a raw webhook body for GitHub, Shopify, Stripe, Slack or a custom scheme and compare it with the received signature header. valid is true only when the signature matches and, for timestamped schemes, the timestamp is within the tolerance window (Stripe/Slack 300 seconds). On mismatch, diagnostics explain common causes: wrong prefix, hex/base64 mix-up, missing timestamp, whitespace, or a re-serialized JSON body. Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx/5xx. Sensitive: request bodies are processed in memory only and are never stored, logged or hashed into usage records.

POST/v1/run/webhook/verify

Access requirements

Health, metadata, changelog and waitlist routes are public. Catalog reads (GET /v1/tools, /v1/tools/{id}, /v1/colors/*) and POST /v1/tools/query require a tools.read credential; POST /v1/run/* requires tools.run. There is no anonymous access to these routes: send an API key (Bearer OR X-API-Key) from your server, or use the HttpOnly main-site session plus workspace selection and same-origin Origin. Never combine credentials. Every admitted call is metered. Ingress and workspace/actor minute/month limits are separate; waitlist has its own policy.

Implemented interfaces and development screens do not imply public production availability, paid access or a completed payment integration. Confirm access with Birdor before connecting an application. No paid Pro service, activation or cross-device sync is currently delivered. We are validating one repeatable task before building a paid offer.

Parameters

FieldDescription
AuthorizationstringOptionalBearer API key with tools.run; alternatively X-API-Key. One of the credentials is required.
X-API-KeystringOptionalAlternative to Authorization; never send both.
X-Birdor-Workspace-IDstringOptionalRequired with the site session; optional and matching with an API key.
X-Birdor-Project-IDstringOptionalOptional owned project; a project-bound key cannot select another project.

Request body

Send JSON with Content-Type: application/json.

FieldDescription
platformgithub | shopify | stripe | slack | customRequiredSignature scheme: github (X-Hub-Signature-256), shopify (X-Shopify-Hmac-Sha256), stripe (Stripe-Signature), slack (X-Slack-Signature) or custom.
payloadstringRequiredRaw request body exactly as received, before any JSON parsing; at most 30000 characters (the whole request body is capped at 32768 bytes).
secretstringRequiredWebhook signing secret. Used in memory for this request only; never stored, logged or hashed into usage records.
secretEncodingutf8 | hex | base64OptionalHow the secret is encoded; default utf8 (Stripe whsec_… and GitHub secrets are utf8).
signaturestringRequiredSignature header value as received, e.g. sha256=… or the full Stripe-Signature t=…,v1=… header.
timestampstringOptionalUnix seconds from the timestamp header. Required for slack and for custom schemes with requiresTimestamp; Stripe reads t= from the header.
customobjectOptionalRequired when platform is custom: algorithm, encoding, prefix, requiresTimestamp, toleranceSeconds and messageTemplate ({timestamp}/{payload}).

Request example

1. Set the base URL

Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/run/webhook/verify" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $BIRDOR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "platform": "github",
  "payload": "Hello, World!",
  "secret": "It'\''s a Secret to Everybody",
  "signature": "sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17"
}'

Examples are copied only; this page does not send API requests.

Responses

Illustrative response. Values vary by environment and time.

200Success
HTTP 200
{
  "ok": true,
  "data": {
    "valid": true,
    "signatureMatched": true,
    "platform": "github",
    "algorithm": "SHA-256",
    "encoding": "hex",
    "expectedSignature": "sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17",
    "timestamp": null,
    "diagnostics": []
  },
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
400Invalid JSON, schema validation failure (field paths/codes only, never input values) or ambiguous credentials
HTTP 400
{
  "ok": false,
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
401Missing, expired, rotated, revoked or invalid credential; there is no anonymous access
HTTP 401
{
  "ok": false,
  "code": "UNAUTHENTICATED",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
403Key lacks tools.run, or workspace/project/member policy or site Origin denied
HTTP 403
{
  "ok": false,
  "code": "FORBIDDEN",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
405Only POST is supported; rejected before admission
HTTP 405
{
  "ok": false,
  "code": "METHOD_NOT_ALLOWED",
  "message": "Method not allowed",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
408Body read exceeds five seconds; before admission
HTTP 408
{
  "ok": false,
  "code": "REQUEST_TIMEOUT",
  "message": "Request body timeout or aborted",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
413Body exceeds 32768 bytes; before admission
HTTP 413
{
  "ok": false,
  "code": "PAYLOAD_TOO_LARGE",
  "message": "Request body too large",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
415Content-Type must be application/json; before admission
HTTP 415
{
  "ok": false,
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "JSON content type required",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
429Ingress, workspace/actor minute or monthly quota exceeded; inspect code and Retry-After
HTTP 429
{
  "ok": false,
  "code": "QUOTA_EXCEEDED",
  "message": "API request limit exceeded",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
500Unexpected operation failure; details are never echoed
HTTP 500
{
  "ok": false,
  "code": "OPERATION_FAILED",
  "message": "Operation failed",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
503Authentication/metering dependency unavailable
HTTP 503
{
  "ok": false,
  "code": "API_GATEWAY_UNAVAILABLE",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
422CUSTOM_CONFIG_REQUIRED: platform is custom but custom is missing; TIMESTAMP_REQUIRED: The scheme signs a timestamp but none was supplied (Stripe header t=, timestamp field for Slack/custom); INVALID_TIMESTAMP: The Stripe-Signature t= value is not Unix seconds; INVALID_SECRET: secret cannot be decoded with secretEncoding
HTTP 422
{
  "ok": false,
  "code": "CUSTOM_CONFIG_REQUIRED",
  "message": "platform is custom but custom is missing",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
Error handling

Example response fields

Fields shown in this example; optional fields can be omitted. Array rows describe the first example element.

okboolean
Application success flag.
dataobject
Endpoint-specific result.
data.validboolean
True when the signature matches and any signed timestamp is within tolerance.
data.signatureMatchedboolean
Whether the received signature equals the recomputed one.
data.platformstring
Signature scheme used.
data.algorithmstring
HMAC hash algorithm.
data.encodingstring
Signature encoding (hex or base64).
data.expectedSignaturestring
Signature recomputed from the payload, including the scheme prefix.
data.timestampnull
Response creation timestamp.
data.diagnosticsarray
Likely causes when verification fails.
request_idstring
Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
timestampstring
Response creation timestamp.