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.
/v1/run/webhook/verifyAccess 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
| Field | Description |
|---|---|
AuthorizationstringOptional | Bearer API key with tools.run; alternatively X-API-Key. One of the credentials is required. |
X-API-KeystringOptional | Alternative to Authorization; never send both. |
X-Birdor-Workspace-IDstringOptional | Required with the site session; optional and matching with an API key. |
X-Birdor-Project-IDstringOptional | Optional owned project; a project-bound key cannot select another project. |
Request body
Send JSON with Content-Type: application/json.
| Field | Description |
|---|---|
platformgithub | shopify | stripe | slack | customRequired | Signature scheme: github (X-Hub-Signature-256), shopify (X-Shopify-Hmac-Sha256), stripe (Stripe-Signature), slack (X-Slack-Signature) or custom. |
payloadstringRequired | Raw request body exactly as received, before any JSON parsing; at most 30000 characters (the whole request body is capped at 32768 bytes). |
secretstringRequired | Webhook signing secret. Used in memory for this request only; never stored, logged or hashed into usage records. |
secretEncodingutf8 | hex | base64Optional | How the secret is encoded; default utf8 (Stripe whsec_… and GitHub secrets are utf8). |
signaturestringRequired | Signature header value as received, e.g. sha256=… or the full Stripe-Signature t=…,v1=… header. |
timestampstringOptional | Unix seconds from the timestamp header. Required for slack and for custom schemes with requiresTimestamp; Stripe reads t= from the header. |
customobjectOptional | Required when platform is custom: algorithm, encoding, prefix, requiresTimestamp, toleranceSeconds and messageTemplate ({timestamp}/{payload}). |
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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"ok": false,
"code": "OPERATION_FAILED",
"message": "Operation failed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}503Authentication/metering dependency unavailable
{
"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
{
"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"
}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.