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 awebhook-signaturecarrying one or more space-separatedv1,<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.
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
v1example from the specification, - an asymmetric
v1aEd25519 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.