Securing a webhook event source
Webhook Events verifies every incoming request before publishing an event. You choose one authentication type when you create a webhook event source: an HMAC signature, a static token, or basic authentication. EventBridge stores the associated credential as a secret in AWS Secrets Manager in your account and verifies each request against it. This section describes the authentication types, how EventBridge stores and rotates the credential, and what you can change after the event source is created.
The authentication type is set when you create the event source and cannot be changed afterward. If you need a different authentication type, create a new webhook event source. See Create a webhook event source.
This section contains the following topics:
Choosing an authentication type
You specify exactly one authentication type in the AuthConfiguration of the
webhook configuration when you create the event source:
- HMAC signature (
HmacAuthConfiguration) The sending system signs each request with a shared secret and includes the signature in a header. EventBridge recomputes the signature and compares it. Use this when your provider supports signed webhooks. See HMAC signature verification.
- Static token (
StaticTokenAuthConfiguration) The sending system includes a fixed secret token in a header that you name. EventBridge compares the header value to the stored token. See Static token authentication.
- Basic authentication (
BasicHttpAuthConfiguration) The sending system authenticates with a user name and password using HTTP basic authentication. See Basic authentication.
For each type, you can either supply your own secret value or omit it and let EventBridge generate one. For how the credential is stored, see How the credential is stored.
HMAC signature verification
With HMAC authentication, the sending system computes a hash-based message
authentication code over the request and sends it in a header. EventBridge recomputes the code
with the shared secret and rejects the request if it does not match. Configure
HmacAuthConfiguration with the following fields.
| Field | Required | Values | Description |
|---|---|---|---|
Algorithm |
Yes | SHA256, SHA1 |
The hash algorithm used to compute the signature. |
Encoding |
Yes | HEX, BASE64 |
How the computed signature is encoded in the header. |
SignatureHttpHeader |
Yes | Header name | The header that carries the signature. |
SignedMessageComposition |
Yes | BODY, TIMESTAMP_DOT_BODY,
MESSAGE_ID_DOT_TIMESTAMP_DOT_BODY |
Which parts of the request are concatenated to form the signed message. |
TimestampHttpHeader |
Conditional | Header name | The header that carries the request timestamp. Required for the composition values that include a timestamp. |
TimestampToleranceInSeconds |
No | 1 to 900 seconds (default 300) | How far the request timestamp may differ from the current time before the request is rejected as expired. |
MessageIdHttpHeader |
Conditional | Header name | The header that carries a unique message ID. Required for the message-ID composition value. |
SignaturePrefix |
Conditional | 1 to 64 characters | A prefix that precedes the signature value in the header. |
TimestampPrefix |
Conditional | 1 to 64 characters | A prefix that precedes the timestamp value. |
Delimiter |
Conditional | 1 to 64 characters | The separator between parts of the signature header value, such as a comma in a value like t=1727816400,v1=signature, or a space when the header carries several signatures. When the signature and timestamp share one header, it also separates those two values. |
SecretValue |
No | 6 to 512 characters encoding to 16 to 512 bytes | The signing secret. With BASE64 SecretEncoding, the value is a base64 string that EventBridge decodes to the signing key. If you omit it, EventBridge generates one. See
How the credential is stored. |
SecretEncoding |
No | RAW, BASE64 (default RAW) |
How EventBridge decodes the secret before using it to sign. |
Several fields are required only in combination with others. EventBridge rejects a
configuration that violates one of these rules with an
InvalidInputException (HTTP 400):
TIMESTAMP_DOT_BODYandMESSAGE_ID_DOT_TIMESTAMP_DOT_BODYrequireTimestampHttpHeader.MESSAGE_ID_DOT_TIMESTAMP_DOT_BODYalso requiresMessageIdHttpHeader.Setting
TimestampToleranceInSecondsrequiresTimestampHttpHeader.The
BODYcomposition signs only the body, so it rejectsTimestampHttpHeaderandTimestampToleranceInSeconds.When the timestamp and the signature use the same header (that is,
TimestampHttpHeaderequalsSignatureHttpHeader),Delimiter,SignaturePrefix, andTimestampPrefixare all required so that EventBridge can separate the two values.
The following AWS CLI example configures HMAC authentication that signs the concatenation of the timestamp and the body, with EventBridge generating the secret.
aws eventsv2 create-event-source \ --name orders-provider-hmac \ --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \ --configuration '{ "WebhookEventsConfiguration": { "AuthConfiguration": { "HmacAuthConfiguration": { "Algorithm": "SHA256", "Encoding": "HEX", "SignatureHttpHeader": "X-Signature", "SignedMessageComposition": "TIMESTAMP_DOT_BODY", "TimestampHttpHeader": "X-Timestamp", "TimestampToleranceInSeconds": 300 } }, "RoleArn": "arn:aws:iam::111122223333:role/orders-provider-webhook-role", "KmsKeyIdentifier": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } }'
Support for the Standard Webhooks specification
The HMAC fields let you match the signing scheme of many webhook providers. Because providers differ in how they name headers, order the signed fields, and format the signature value, not every provider's scheme can be expressed with these options.
Where a provider gives you a choice, we recommend the Standard Webhooks specification, a common signing scheme supported by many webhook providers. Webhook Events verifies requests
signed according to the Standard Webhooks specification; configure
HmacAuthConfiguration as follows.
aws eventsv2 create-event-source \ --name orders-provider-standard-webhooks \ --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \ --configuration '{ "WebhookEventsConfiguration": { "AuthConfiguration": { "HmacAuthConfiguration": { "Algorithm": "SHA256", "Encoding": "BASE64", "SignedMessageComposition": "MESSAGE_ID_DOT_TIMESTAMP_DOT_BODY", "SignatureHttpHeader": "webhook-signature", "SignaturePrefix": "v1,", "Delimiter": " ", "MessageIdHttpHeader": "webhook-id", "TimestampHttpHeader": "webhook-timestamp", "SecretEncoding": "BASE64", "SecretValue": "your-provider-signing-secret" } }, "RoleArn": "arn:aws:iam::111122223333:role/orders-provider-webhook-role" } }'
Supply the signing secret your provider issues in SecretValue. EventBridge
reads the message ID from the webhook-id header and the timestamp from
the webhook-timestamp header, verifies the base64 signature carried as a
space-delimited list of v1,-prefixed values in the
webhook-signature header, and rejects requests whose timestamp falls
outside TimestampToleranceInSeconds (300 seconds by default).
If your provider issues a signing secret with a whsec_ prefix (the
Standard Webhooks convention) and you set SecretEncoding to
BASE64, EventBridge removes the whsec_ prefix before it decodes the
secret. With SecretEncoding set to RAW (the default), EventBridge
uses the secret exactly as you provide it, including any prefix.
Static token authentication
With static token authentication, the sending system includes a fixed secret token in a
header that you name, and EventBridge compares the header value to the stored token. Configure
StaticTokenAuthConfiguration:
TokenHttpHeader(required)The header that carries the token.
SecretValue(optional, 6 to 512 characters)The token value. If you omit it, EventBridge generates one. See How the credential is stored.
Static token authentication verifies the caller but does not protect the integrity of each request. For stronger protection, use HMAC signature verification with a timestamp, which adds message integrity and replay-attack protection. See HMAC signature verification.
Basic authentication
With basic authentication, the sending system authenticates with a user name and
password using HTTP basic authentication. Configure BasicHttpAuthConfiguration with Username (1 to 512 characters) and Password (6 to 512 characters).
Supply both values or omit both. If you omit both, EventBridge generates the user name and
password. If you supply only one of the two, EventBridge rejects the request with an InvalidInputException (HTTP 400).
Basic authentication verifies a user name and password but does not protect the integrity of each request. For stronger protection, use HMAC signature verification with a timestamp, which adds message integrity and replay-attack protection. See HMAC signature verification.
How the credential is stored
For every authentication type, EventBridge stores the credential as a secret in Secrets Manager in your
account and verifies incoming requests against it. EventBridge returns the ARN of that secret,
not the secret value, in the EventSourceDetails.WebhookDetails.SecretArn field of the
CreateEventSource and DescribeEventSource responses.
- Service-generated credential
Omit the secret value (
SecretValuefor HMAC and static token, or bothUsernameandPasswordfor basic authentication). EventBridge generates a credential, stores it, and returns the secret ARN.- Bring your own credential
Provide the secret value in the authentication configuration. EventBridge stores the value you provide. You do not pass a secret ARN; EventBridge creates the secret and returns its ARN.
EventBridge never returns the secret value from any operation, including
DescribeEventSource. Only the secret's ARN is returned. When EventBridge
generates the credential for you, retrieve its value from Secrets Manager and configure it in
the sending system, so that the sending system authenticates with the same
credential EventBridge verifies against.
You can encrypt the secret with a customer managed AWS KMS key by specifying
KmsKeyIdentifier. Secrets Manager calls AWS KMS on behalf of the identity that uses the secret, so the key policy must allow that identity: your identity when you create or rotate the credential, and the event source's role (RoleArn) when EventBridge reads the secret to verify requests. If you omit
KmsKeyIdentifier, EventBridge encrypts the secret with the AWS managed key for
Secrets Manager (aws/secretsmanager). You can change the key after creation; see
Updating your webhook event source.
Rotating the credential
Use RotateWebhookCredentials to replace the credential without changing
the webhook URL or the secret ARN. EventBridge stores the new credential as a new version of the
same secret and invalidates the previous one. For basic authentication, only the
password is replaced; the user name doesn't change.
aws eventsv2 rotate-webhook-credentials \ --event-source-arn arn:aws:events:us-east-1:111122223333:event-sourcev2/webhook/orders-provider/EXAMPLE1234567890abcde
The response returns only the SecretArn, which does not change on
rotation. RotateWebhookCredentials does not return the new credential; to
read a generated value, call secretsmanager:GetSecretValue on that secret.
After rotation, EventBridge continues to accept the previous credential for 15 minutes, so update the sending system within that window.
To supply your own new credential instead of having EventBridge generate one, pass it to
RotateWebhookCredentials. If you don't supply a value, EventBridge
generates a new credential. The credential changes only through
RotateWebhookCredentials; UpdateEventSource doesn't
accept a secret value, user name, or password.
Updating your webhook event source
Some parts of a webhook event source are fixed when you create it:
The authentication type, and the HMAC
SecretEncoding, cannot be changed after creation. You can change other HMAC settings, such as the header names, signed-message composition, prefixes, and timestamp tolerance, withUpdateEventSource.The webhook URL and the secret ARN do not change for the life of the event source.
UpdateEventSourcenever changes either one, and rotating the credential does not change them.
You can change the AWS KMS key after creation with UpdateEventSource: switch to a different customer managed key, or between a customer managed key and the AWS managed key for Secrets Manager. AWS KMS key rotation does not affect the secret.
To change the authentication type, create a new webhook event source. To replace the credential, rotate it as described in Rotating the credential.