How webhooks work
Webhooks are HTTP POST requests sent to your specified endpoint whenever certain events occur in your repositories. When you create a webhook subscription, Code Storage will:- Monitor Events: Watch for the events you’ve subscribed to (e.g.,
pushorrepo.sync.*events) - Generate Payloads: Create JSON payloads containing event details
- Sign Requests: Add cryptographic signatures for security verification
- Deliver Webhooks: Send HTTP POST requests to your endpoint with automatic retries
Webhook headers
Every webhook request includes the following headers:Content-Type: application/jsonUser-Agent: Pierre-Webhook/1.0X-Pierre-Event: <event_type>(e.g.,push,repo.sync.started,repo.sync.succeeded,repo.sync.failed)X-Pierre-Signature: t=1642678200,sha256=abc123...(security signature)
Custom headers
Add static headers in the webhook editor to authenticate requests or attach routing metadata, for exampleAuthorization: Bearer <token> or X-Environment: production.
- Each subscription supports up to 10 custom headers, with 8 KiB total across names, values,
and the
:and line-ending separators (4 bytes per header). - Custom headers require an HTTPS endpoint.
- Names may contain ASCII letters, digits, and hyphens. Names are case-insensitive and must be unique. Values must contain printable ASCII characters, without leading or trailing whitespace.
- Values are encrypted when stored. After saving, only names are returned; use Replace value to enter a new value, Save value to keep that edit in the form, Cancel to keep the saved value, or Remove header to delete the header. Save the webhook to apply the changes.
- Changing the webhook URL preserves its saved headers.
- If saved headers cannot be read, the editor shows a warning. You can still disable or delete the webhook, or clear or replace its saved headers. Other webhook settings preserve the saved values.
- Pierre’s own headers:
X-Pierre*andX-Git3P*. - Connection and framing headers:
Host,User-Agent,Content-*,Connection,Keep-Alive,Transfer-Encoding,TE,Trailer,Upgrade,Expect,Accept-Encoding,HTTP2-Settings, andProxy-*. - Client identity headers added by proxies and CDNs:
Forwarded,Via,X-Forwarded-*,X-Envoy-*,X-Real-IP,X-Client-IP,True-Client-IP,X-Cluster-Client-IP,CF-Connecting-IP,CF-Connecting-IPv6,CF-Ray,Fastly-Client-IP, andCDN-Loop. - Trace propagation headers:
Traceparent*,Tracestate*,Traceresponse*,Baggage*,X-Cloud-Trace-Context,X-Amzn-Trace-Id, andX-Amz-Cf-Id. - gRPC headers:
Grpc-*.
Event types
Common fields
Use these fields to identify the event, repository, and organization:push
Triggered when commits are pushed to a repository.
repo.sync.started
Triggered when a repository sync run begins, before the upstream fetch executes. After a run fails,
a later run of the same failing series sends this event only when it succeeds: at the end of the
run, right before repo.sync.succeeded. Thus this event does not show that a retry is in progress.
During the move to the new sync engine, some repositories send repo.sync.started at the start of
every run, also after a failure. On these repositories, a run that starts after a failure can still
fail. Also during the move, one sync of each repository sends repo.sync.started and
repo.sync.succeeded only when it changes refs.
repo.sync.succeeded
Triggered when a sync run completes successfully. If an earlier run of the same series failed, Code
Storage sends repo.sync.started right before this event. During the move to the new sync engine,
some repositories send repo.sync.started at the start of the run instead.
Each event has its own delivery and its own retries, so deliveries can arrive out of order. For
example, repo.sync.succeeded can arrive before the repo.sync.started of the same run. The events
of one run have the same started_at, and repo.sync.started has a run_count that is 1 lower
than the end event. Use these fields to order the events of a run.
repo.sync.failed
Triggered at the first failure of a series of failed sync runs. Code Storage retries a sync that
fails with a transient error for up to 2 hours. A later run of the series that fails again with a
transient error does not send this event. An error that a retry cannot fix always sends it. When the
retries stop, no event is sent, and the next sync trigger starts a new series.
During the move to the new sync engine, some repositories get repo.sync.failed once per run, when
the retries of that run end.
Sync event fields
Cancellations triggered internally (e.g., when a repository is detached from its upstream) do not
produce a
repo.sync.failed event.Securing webhooks
To ensure the webhooks you receive are legitimate and from Code Storage, you must verify the HMAC signature included with each webhook delivery.HMAC Signature Verification
Each webhook includes anX-Pierre-Signature header with the format:
Webhook SDK methods
The SDK provides a helper function to verify webhook events quickly:verifyWebhook in TypeScript,
verify_webhook in Python, and webhooks.VerifyWebhook in Go. It checks the signature and the
timestamp, then returns the event with its type.
Advanced SDK usage
Custom Validation Options:Common verification errors
When the check fails, the SDK raisesWebhookVerificationError. In Go, webhooks.VerifyWebhook
returns a *pierre.WebhookVerificationError. Its reason field (Reason in Go) names the failure:
- Missing signature components:
malformed_signature - Timestamp too old:
timestamp_out_of_range - Future timestamp:
timestamp_out_of_range - Signature mismatch:
signature_mismatch - Invalid JSON:
invalid_payload(also for a payload with no event type) - Missing headers:
missing_signature(noX-Pierre-Signatureheader)
PierreError with no reason (*pierre.PierreError in
Go).
Error Handling Best Practices: