Inbound endpoints
Inbound endpoints let external systems trigger Puck investigations without going through the console or the investigation API directly. You create an endpoint, give the generated URL to the third-party tool (as a webhook destination), and Puck handles translation: when an alert or event arrives, the brain maps it to an investigation query and queues the run automatically.
The inbound endpoint surface is documented on the Webhooks API page, under the POST /v1/webhooks/incoming/endpoints, GET /v1/webhooks/incoming/endpoints, DELETE /v1/webhooks/incoming/endpoints/{id}, and POST /v1/webhooks/incoming/{provider}/{key} sections.
This page covers the operational details that don’t fit naturally in the endpoint reference.
Supported providers
| Provider | How it maps to investigations |
|---|---|
generic | Body must include query (string) and optionally agent_ids or a scope object. The body is passed directly to the investigation trigger. |
crowdstrike | CrowdStrike alert webhooks are parsed; the device_id maps to an agent, the alert description becomes the investigation query. Unrecognised event types are accepted but ignored (202 with "ignored": true). |
github | GitHub workflow_run and security_advisory events are mapped to investigations against the affected repository’s CI runners. ping events return 202 Accepted with "ignored": true. |
URL security model
The receiver URL contains an embedded secret in the path (/v1/webhooks/incoming/{provider}/{key}). Anyone in possession of the URL can POST events that trigger investigations. Treat the URL like a password:
- Store it in your provider’s secret vault, not in plain config files.
- Rotate it by deleting the endpoint and creating a new one.
- Use
provider_signing_secret(the HMAC key your provider uses to sign deliveries) to add an integrity layer on top of URL-based auth.
Signature verification
When provider_signing_secret is set, Puck verifies the provider’s delivery signature on each inbound POST before processing it:
- GitHub:
X-Hub-Signature-256header, HMAC-SHA256 of the raw body using your GitHub webhook secret. - CrowdStrike:
X-Cs-Signatureheader, CrowdStrike’s proprietary signing scheme. - Generic: No signature scheme defined — use URL security or mutual TLS at the network layer.
A failed signature check returns 401 Unauthorized and the event is not processed.
Event deduplication
Puck does not deduplicate inbound events across retries from the provider side. If your provider retries a delivery (e.g. because Puck’s 202 was not received in time), a second investigation may be queued for the same underlying event. Use an idempotency_key in the request body (for the generic provider) or implement deduplication downstream using the investigation’s context.trigger_id field.
Viewing delivery history
Inbound receipts are not surfaced in GET /v1/webhooks/deliveries (that endpoint covers outbound deliveries). Check the investigations list (GET /v1/investigations) filtered by context.trigger_source to audit which inbound events produced investigations.
Common questions
Can I use one endpoint for all providers? No. Each endpoint is bound to a single provider at creation time. Create separate endpoints for CrowdStrike and GitHub if you need both.
What happens if the investigation can’t be queued (e.g. rate limit hit)?
The receiver still returns 202 Accepted but the investigation_id will be absent. Check the response body for an error key with a reason.
Can I update the default_scope or default_depth on an existing endpoint?
Not yet — the PATCH endpoint for inbound configurations is on the roadmap. For now, delete and recreate the endpoint with the new settings.