Skip to content
Sigvane Docs

Webhook signatures and stored data

GitHub webhooks should be signed with the signing secret from your Sigvane inbox. Sigvane checks that signature before it stores the delivery.

This page explains the acceptance path for GitHub webhooks and the data you can expect to read later from the API or CLI.

What Sigvane Verifies

Section titled “What Sigvane Verifies”

Each Sigvane inbox has its own signing secret. When GitHub sends a webhook delivery, it signs the raw request body and includes the signature in the X-Hub-Signature-256 header.

Sigvane verifies the delivery against the signing secret for the inbox in the webhook URL. The request must include one well-formed X-Hub-Signature-256 value using GitHub’s sha256= format, and the signature must match the raw request body.

If the signature is missing, malformed, duplicated, or signed with the wrong secret, Sigvane rejects the request. Rejected requests are not stored as inbox items.

What Accepted Means

Section titled “What Accepted Means”

A webhook delivery is accepted only after Sigvane:

  1. Matches the request to one inbox.
  2. Checks the request is valid for webhook ingestion.
  3. Verifies the GitHub signature.
  4. Stores the resulting inbox item.

When GitHub receives a 200 response from Sigvane, it means Sigvane stored the inbox item. It does not mean your CLI worker, agent, script, or automation has already processed it.

What Gets Stored

Section titled “What Gets Stored”

An accepted delivery becomes one inbox item.

Inbox items include:

  • an inbox item id
  • the inbox id and inbox slug
  • when Sigvane recorded the item
  • when the item expires
  • selected request headers
  • the raw request body, returned by the API as base64
  • providerDeliveryId, when GitHub sent an X-GitHub-Delivery header

For GitHub webhooks, providerDeliveryId comes from the first X-GitHub-Delivery value. Use it when you need to correlate an inbox item with GitHub Recent Deliveries or make your handler safe against duplicate deliveries.

Header Handling

Section titled “Header Handling”

Sigvane stores a filtered set of headers, not every header on the request.

For GitHub webhooks, Sigvane stores:

  • content-type
  • GitHub headers that start with x-github-

Stored header names are lowercased. Header values are arrays, so repeated header values can be preserved.

Sigvane does not store GitHub signature headers:

  • x-hub-signature
  • x-hub-signature-256

Sigvane also excludes transport and proxy headers, such as headers added by load balancers or CDN layers.

Body Handling

Section titled “Body Handling”

Sigvane treats the request body as opaque bytes. It does not parse GitHub payloads into provider-specific fields.

When you read an inbox item through the API or use stdin: full_item in the CLI, the body field is base64-encoded. Decode it before parsing the GitHub JSON payload.

If your CLI handler uses stdin: body, the CLI decodes the body bytes before sending them to your command.

Duplicate Deliveries

Section titled “Duplicate Deliveries”

Duplicate inbox items can happen. GitHub may redeliver a webhook, and a worker can see the same item again after an interruption or handler failure.

Design handlers so they can safely process the same providerDeliveryId more than once.

Section titled “Related Guides”
  • Connect GitHub shows how to configure the webhook URL and signing secret in GitHub.
  • Troubleshooting helps diagnose failed deliveries and empty inboxes.
  • CLI operations explains handler replay and state reset behavior.