com.philiprehberger:webhook-signature
v0.1.5680 downloadsMIT
HMAC webhook signature creation and verification with timing-safe comparison
$
implementation com.philiprehberger:webhook-signatureREADME
webhook-signature
HMAC webhook signature creation and verification with timing-safe comparison.
Installation
Gradle (Kotlin DSL)
implementation("com.philiprehberger:webhook-signature:0.1.4")
Maven
<dependency>
<groupId>com.philiprehberger</groupId>
<artifactId>webhook-signature</artifactId>
<version>0.1.4</version>
</dependency>
Usage
import com.philiprehberger.webhooksignature.*
val signer = WebhookSigner("my-secret", HmacAlgorithm.SHA256)
val timestamp = System.currentTimeMillis() / 1000
// Sign a payload
val signature = signer.sign("""{"event":"order.created"}""", timestamp)
// Verify a payload
val valid = signer.verify("""{"event":"order.created"}""", signature, timestamp)
Provider-Specific Signers
// Stripe
val stripeSigner = WebhookSigner.stripe("whsec_your_secret")
// GitHub
val githubSigner = WebhookSigner.github("your_webhook_secret")
Parsing Provider Headers
// Stripe: "t=1234567890,v1=abc123..."
val (timestamp, sig) = parseStripeSignatureHeader(request.getHeader("Stripe-Signature"))!!
// GitHub: "sha256=abc123..."
val sig = parseGithubSignatureHeader(request.getHeader("X-Hub-Signature-256"))!!
Custom Tolerance
import kotlin.time.Duration.Companion.minutes
// Reject signatures older than 10 minutes
signer.verify(payload, signature, timestamp, tolerance = 10.minutes)
// Disable timestamp checking
signer.verify(payload, signature, timestamp, tolerance = Duration.ZERO)
API
| Function / Class | Description |
|---|---|
WebhookSigner(secret, algorithm) | Create a signer with HMAC algorithm |
WebhookSigner.sign(payload, timestamp) | Sign a payload, returns hex signature |
WebhookSigner.verify(payload, signature, timestamp, tolerance) | Verify a signature with timing-safe comparison |
WebhookSigner.stripe(secret) | Factory for Stripe-compatible signer |
WebhookSigner.github(secret) | Factory for GitHub-compatible signer |
HmacAlgorithm | Enum: SHA1, SHA256, SHA512 |
parseStripeSignatureHeader(header) | Parse Stripe signature header |
parseGithubSignatureHeader(header) | Parse GitHub signature header |
Development
./gradlew test # Run tests
./gradlew check # Run all checks
./gradlew build # Build JAR
Support
If you find this project useful: