Skip to main content

Signatures and interop

The default dialect is Standard Webhooks — byte-compatible with the specification and its official SDKs, so any Standard Webhooks consumer can verify our deliveries and we can verify theirs.

  • Signed content: {webhook-id}.{webhook-timestamp}.{rawBody}, HMAC-SHA256, base64-encoded.
  • Headers: webhook-id, webhook-timestamp, and a webhook-signature carrying one or more space-separated v1,<base64> entries (a rotation emits two — accept if either verifies).
  • Key derivation: strip an optional whsec_ prefix, then base64-decode the remainder to the raw HMAC key bytes.

The other schemes​

Other schemes ship for interop: StripeScheme, GitHubScheme, PlainHmacScheme and SecretTokenScheme (receive adapters for those producers), and the asymmetric Ed25519Scheme — the Standard Webhooks v1a variant, which carries a webhook-signature: v1a,<base64> entry so a receiver only ever holds the public key.

Generate a keypair with php artisan webhooks:ed25519-keygen or Pushery\Webhooks\Core\Signing\Ed25519Keys::generate(). A receiver may pin a static public key or point jwks.url at the producer's JSON Web Key Set of Ed25519 keys — fetched through the SSRF guard and cached for jwks.cache_ttl seconds, one hour by default — for rotating provider keys.

Either form selects Ed25519Scheme when the entry names no scheme. An entry that names a shared-secret scheme for them is refused as a configuration fault, because an HMAC under a public key is a signature anyone can compute. A raw base64 key without the whpk_ prefix cannot be told apart from a shared secret, so for one, name the scheme.

That default is the one number to check against your producer's rotation schedule. A producer that rotates faster than the cache window signs with a key this side has not fetched yet, and an unresolvable key is refused as unsigned — the same silent refusal the warning below describes. Lower cache_ttl to below the producer's rotation interval, or pin kid and rotate the pin yourself.

Two keys, chosen by position

Without a pinned kid, the first two keys of the document are tried, in the order the document publishes them. That is a statement about position, not about age: a JWK carries no reliable age, and RFC 7517 defines no ordering for keys. With one or two keys it makes no difference — both are tried either way. With three or more, everything past the second is never tried, and a delivery signed with one of those keys is refused as unsigned: no error, no log, just a producer retrying until its budget is gone. Pin kid when the producer publishes more than two.

Which adapter to select per inbound source is on the Receiving page.

A producer with a different header name​

A producer that uses a different header name needs no scheme class of its own: set signature_headers.signature and it is injected into any header-overridable scheme (e.g. PlainHmacScheme for SendCloud's Sendcloud-Signature).

A key you omit keeps the scheme's own default, so GitHubScheme keeps X-Hub-Signature-256; StripeScheme's header is fixed.

A producer that sends its secret as a token​

GitLab sends the secret of a webhook as it is, in X-Gitlab-Token, when no signing token is set. SecretTokenScheme compares that header with secret and, during a rotation, with previous_secret, in constant time:

[
'name' => 'gitlab',
'secret' => env('GITLAB_WEBHOOK_TOKEN'),
'scheme' => \Pushery\Webhooks\Core\Signing\SecretTokenScheme::class,
'event_type' => 'header:X-Gitlab-Event',
],

A producer that sends its token in another header names it in signature_headers.signature. The token is no signature: it travels with every delivery and covers no body, so anybody who has read one delivery can send others. Where the producer can sign, verify that instead. The scheme carries no timestamp and no delivery id, so set dedupe_id to a key the producer keeps across retries.

A producer that sends the digest as Base64​

Shopify and WooCommerce sign the raw body with HMAC-SHA256 as SendCloud does, and write the digest as Base64 instead of hex. PlainHmacScheme reads that from config too: set signature_encoding to base64 beside the header name.

[
'name' => 'shopify',
'secret' => env('SHOPIFY_WEBHOOK_SECRET'),
'scheme' => \Pushery\Webhooks\Core\Signing\PlainHmacScheme::class,
'signature_headers' => ['signature' => 'X-Shopify-Hmac-Sha256'],
'signature_encoding' => 'base64',
],

WooCommerce is the same entry with X-WC-Webhook-Signature. Hex stays the default. A signature in the other encoding never matches, and the refusal looks exactly like a wrong secret, so a producer that is refused from its first delivery is worth checking for this before the secret. Only PlainHmacScheme reads the option: every other scheme's format is fixed by its dialect, and an entry that names an encoding for one is refused when the config loads.

Verification that is not a signature​

Some providers can't be verified by a pure function of the bytes: Mollie signs nothing (authenticity is an authenticated API call back to it), PayPal verifies through a cert-chain API keyed on a webhook ID, not a secret. Point a config's verifier at a Pushery\Webhooks\Client\Verification\InboundVerifier — see Receiving.

Calls between services​

A delivery is signed over its body, because the endpoint it goes to acts on nothing else. A call to an API names what it acts on in its address, the hold in /holds/7/release, and one secret usually signs every call of a connection. Signed over the body alone, a call that was seen once could be sent again to every other address of the connection until its timestamp runs out. So a call is signed over its method, a space, its target, a line feed and its body:

POST /holds/7/release?notify=1
{"reason":"expired"}
  • Target: the path and the query as sent, without scheme and host. A target holds no whitespace, so the space ends the method and the line feed ends the target, and no part can be moved into another.
  • Method: uppercased, the way a receiving server reads it.
  • Signature: the scheme signs that content where it would sign the body of a delivery. Under Standard Webhooks that is {webhook-id}.{webhook-timestamp}.{content}, carried in the same three headers.

Sign an outgoing call with the SignsRequests middleware on Laravel's HTTP client:

use Illuminate\Support\Facades\Http;
use Pushery\Webhooks\Core\Signing\SecretSet;
use Pushery\Webhooks\Core\Signing\SignsRequests;
use Pushery\Webhooks\Core\Signing\StandardWebhooksScheme;

Http::withoutRedirecting()
->withMiddleware(new SignsRequests(new StandardWebhooksScheme(), SecretSet::fromCurrent($secret)))
->post('https://partner.example/holds/7/release?notify=1', ['reason' => 'expired']);

It signs the request as it leaves, so the signature covers the body the client built and the target it resolved, and each call and each retry gets a fresh id and timestamp. A call that would follow a redirect is refused with an InvalidMessage before anything is sent: a followed redirect is a second request, to an address the receiver chose, and the client would sign that one as well.

Verify an incoming call with the VerifySignedRequest middleware, naming a config in webhooks.client.configs:

use Illuminate\Support\Facades\Route;
use Pushery\Webhooks\Client\Http\VerifySignedRequest;

Route::post('/holds/{hold}/release', ReleaseHold::class)
->middleware(VerifySignedRequest::class.':partner');

The config verifies the call the way it verifies a delivery: with its secret, its jwks keys or the secrets its tenant_resolver names, under its scheme and its tolerance. A refused call never reaches the route; it is answered with the config's invalid_status, or its undetermined_status when the check could not complete, and announced with InvalidWebhookSignature. A config with a verifier takes part only when the verifier implements Pushery\Webhooks\Client\Verification\VerifiesSignedRequests, which is handed the signed content in place of the body. Any other verifier is refused as a configuration fault, because it would check the body alone.

A refusal is a SignedRequestRefused, an HttpException with the status above and no message, so an application that renders nothing of its own answers it as it answers abort() with that status. An API with an error format of its own renders it in bootstrap/app.php, and the call is announced with InvalidWebhookSignature either way:

use Illuminate\Foundation\Configuration\Exceptions;
use Pushery\Webhooks\Client\Exceptions\SignedRequestRefused;

->withExceptions(function (Exceptions $exceptions): void {
$exceptions->render(fn (SignedRequestRefused $refused) => response()->json([
'type' => 'urn:example:problem:invalid-signature',
'status' => $refused->getStatusCode(),
], $refused->getStatusCode(), ['Content-Type' => 'application/problem+json']));
})

It names the config in configName and the verdict in reason: invalid, expired, malformed or undetermined, the values InvalidWebhookSignature carries, or unverifiable for a config that cannot verify any call, which is also reported as the configuration fault it is.

The target is the path and the query as your application receives them, so a proxy that rewrites the path on the way makes every call fail.

Secret rotation​

Secret rotation is first-class: Pushery\Webhooks\Core\Signing\SecretSet::rotating($current, $previous) (or ->useSecrets() on a call) signs with both, so verification never breaks mid-rotation. A delivery signs with the secrets it was queued with for as long as it is retried; one that has to sign with the secrets of each attempt names a ResolvesDeliverySecrets class with ->resolveSecretsUsing(), as Sending shows.

Canonical JSON (opt-in)​

Set server.signing.canonicalize (or ->canonicalizeJson() per call) to sign and send a deterministic, sorted-key body, so a receiver that re-canonicalizes reproduces the exact signed bytes regardless of key order. Off by default — the exact bytes you send are already what is signed.

Published interop vectors​

Known-answer vectors are shipped at resources/interop/standard-webhooks-vectors.json (with a format guide) so a third-party receiver — or a port of the verifier to another language — can prove byte-for-byte compatibility without trusting this package's code.

They cover all three cases an implementer needs:

  • the canonical symmetric v1 example from the specification,
  • an asymmetric v1a Ed25519 vector (public key, message, expected signature — Ed25519 signing is deterministic, so a correct port reproduces it exactly), and
  • negative vectors that must fail to verify, because an implementation that accepts everything also passes every positive test.

Tests in the suite re-verify each shipped vector against the engine, so the published contract can never drift.