feat(api): add webhook signature verification

Author: stainless-app[bot]

increase-java-core/build.gradle.kts

@@ -22,6 +22,7 @@ dependencies {
     api("com.fasterxml.jackson.core:jackson-core:2.18.2")
     api("com.fasterxml.jackson.core:jackson-databind:2.18.2")
     api("com.google.errorprone:error_prone_annotations:2.33.0")
+    api("com.standardwebhooks:standardwebhooks:1.1.0")
 
     implementation("com.fasterxml.jackson.core:jackson-annotations:2.18.2")
     implementation("com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.2")

increase-java-core/src/main/kotlin/com/increase/api/core/UnwrapWebhookParams.kt

@@ -0,0 +1,102 @@
+// File generated from our OpenAPI spec by Stainless.
+
+package com.increase.api.core
+
+import com.increase.api.core.http.Headers
+import java.util.Objects
+import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
+
+class UnwrapWebhookParams
+private constructor(
+    private val body: String,
+    private val headers: Headers?,
+    private val secret: String?,
+) {
+
+    /** The raw JSON body of the webhook request. */
+    fun body(): String = body
+
+    /** The headers from the webhook request. */
+    fun headers(): Optional<Headers> = Optional.ofNullable(headers)
+
+    /** The secret used to verify the webhook signature. */
+    fun secret(): Optional<String> = Optional.ofNullable(secret)
+
+    fun toBuilder() = Builder().from(this)
+
+    companion object {
+
+        /**
+         * Returns a mutable builder for constructing an instance of [UnwrapWebhookParams].
+         *
+         * The following fields are required:
+         * ```java
+         * .body()
+         * ```
+         */
+        @JvmStatic fun builder() = Builder()
+    }
+
+    /** A builder for [UnwrapWebhookParams]. */
+    class Builder internal constructor() {
+
+        private var body: String? = null
+        private var headers: Headers? = null
+        private var secret: String? = null
+
+        @JvmSynthetic
+        internal fun from(unwrapWebhookParams: UnwrapWebhookParams) = apply {
+            body = unwrapWebhookParams.body
+            headers = unwrapWebhookParams.headers
+            secret = unwrapWebhookParams.secret
+        }
+
+        /** The raw JSON body of the webhook request. */
+        fun body(body: String) = apply { this.body = body }
+
+        /** The headers from the webhook request. */
+        fun headers(headers: Headers?) = apply { this.headers = headers }
+
+        /** Alias for calling [Builder.headers] with `headers.orElse(null)`. */
+        fun headers(headers: Optional<Headers>) = headers(headers.getOrNull())
+
+        /** The secret used to verify the webhook signature. */
+        fun secret(secret: String?) = apply { this.secret = secret }
+
+        /** Alias for calling [Builder.secret] with `secret.orElse(null)`. */
+        fun secret(secret: Optional<String>) = secret(secret.getOrNull())
+
+        /**
+         * Returns an immutable instance of [UnwrapWebhookParams].
+         *
+         * Further updates to this [Builder] will not mutate the returned instance.
+         *
+         * The following fields are required:
+         * ```java
+         * .body()
+         * ```
+         *
+         * @throws IllegalStateException if any required field is unset.
+         */
+        fun build(): UnwrapWebhookParams =
+            UnwrapWebhookParams(checkRequired("body", body), headers, secret)
+    }
+
+    override fun equals(other: Any?): Boolean {
+        if (this === other) {
+            return true
+        }
+
+        return other is UnwrapWebhookParams &&
+            body == other.body &&
+            headers == other.headers &&
+            secret == other.secret
+    }
+
+    private val hashCode: Int by lazy { Objects.hash(body, headers, secret) }
+
+    override fun hashCode(): Int = hashCode
+
+    override fun toString() = "UnwrapWebhookParams{body=$body, headers=$headers, secret=$secret}"
+}

increase-java-core/src/main/kotlin/com/increase/api/errors/IncreaseWebhookException.kt

@@ -0,0 +1,5 @@
+package com.increase.api.errors
+
+class IncreaseWebhookException
+@JvmOverloads
+constructor(message: String? = null, cause: Throwable? = null) : IncreaseException(message, cause)

increase-java-core/src/main/kotlin/com/increase/api/services/async/EventServiceAsync.kt

@@ -4,8 +4,10 @@ package com.increase.api.services.async
 
 import com.increase.api.core.ClientOptions
 import com.increase.api.core.RequestOptions
+import com.increase.api.core.UnwrapWebhookParams
 import com.increase.api.core.http.HttpResponseFor
 import com.increase.api.errors.IncreaseInvalidDataException
+import com.increase.api.errors.IncreaseWebhookException
 import com.increase.api.models.events.Event
 import com.increase.api.models.events.EventListPageAsync
 import com.increase.api.models.events.EventListParams
@@ -85,6 +87,14 @@ interface EventServiceAsync {
      */
     fun unwrap(body: String): UnwrapWebhookEvent
 
+    /**
+     * Unwraps a webhook event from its JSON representation.
+     *
+     * @throws IncreaseInvalidDataException if the body could not be parsed.
+     * @throws IncreaseWebhookException if the webhook signature could not be verified
+     */
+    fun unwrap(unwrapParams: UnwrapWebhookParams): UnwrapWebhookEvent
+
     /** A view of [EventServiceAsync] that provides access to raw HTTP responses for each method. */
     interface WithRawResponse {
 

increase-java-core/src/main/kotlin/com/increase/api/services/async/EventServiceAsyncImpl.kt

@@ -4,6 +4,7 @@ package com.increase.api.services.async
 
 import com.increase.api.core.ClientOptions
 import com.increase.api.core.RequestOptions
+import com.increase.api.core.UnwrapWebhookParams
 import com.increase.api.core.checkRequired
 import com.increase.api.core.handlers.errorBodyHandler
 import com.increase.api.core.handlers.errorHandler
@@ -15,7 +16,6 @@ import com.increase.api.core.http.HttpResponse.Handler
 import com.increase.api.core.http.HttpResponseFor
 import com.increase.api.core.http.parseable
 import com.increase.api.core.prepareAsync
-import com.increase.api.errors.IncreaseInvalidDataException
 import com.increase.api.models.events.Event
 import com.increase.api.models.events.EventListPageAsync
 import com.increase.api.models.events.EventListPageResponse
@@ -53,14 +53,12 @@ class EventServiceAsyncImpl internal constructor(private val clientOptions: Clie
         // get /events
         withRawResponse().list(params, requestOptions).thenApply { it.parse() }
 
-    /**
-     * Unwraps a webhook event from its JSON representation.
-     *
-     * @throws IncreaseInvalidDataException if the body could not be parsed.
-     */
     override fun unwrap(body: String): UnwrapWebhookEvent =
         EventServiceImpl(clientOptions).unwrap(body)
 
+    override fun unwrap(unwrapParams: UnwrapWebhookParams): UnwrapWebhookEvent =
+        EventServiceImpl(clientOptions).unwrap(unwrapParams)
+
     class WithRawResponseImpl internal constructor(private val clientOptions: ClientOptions) :
         EventServiceAsync.WithRawResponse {
 

increase-java-core/src/main/kotlin/com/increase/api/services/blocking/EventService.kt

@@ -5,8 +5,10 @@ package com.increase.api.services.blocking
 import com.google.errorprone.annotations.MustBeClosed
 import com.increase.api.core.ClientOptions
 import com.increase.api.core.RequestOptions
+import com.increase.api.core.UnwrapWebhookParams
 import com.increase.api.core.http.HttpResponseFor
 import com.increase.api.errors.IncreaseInvalidDataException
+import com.increase.api.errors.IncreaseWebhookException
 import com.increase.api.models.events.Event
 import com.increase.api.models.events.EventListPage
 import com.increase.api.models.events.EventListParams
@@ -79,6 +81,14 @@ interface EventService {
      */
     fun unwrap(body: String): UnwrapWebhookEvent
 
+    /**
+     * Unwraps a webhook event from its JSON representation.
+     *
+     * @throws IncreaseInvalidDataException if the body could not be parsed.
+     * @throws IncreaseWebhookException if the webhook signature could not be verified
+     */
+    fun unwrap(unwrapParams: UnwrapWebhookParams): UnwrapWebhookEvent
+
     /** A view of [EventService] that provides access to raw HTTP responses for each method. */
     interface WithRawResponse {
 

increase-java-core/src/main/kotlin/com/increase/api/services/blocking/EventServiceImpl.kt

@@ -5,6 +5,7 @@ package com.increase.api.services.blocking
 import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
 import com.increase.api.core.ClientOptions
 import com.increase.api.core.RequestOptions
+import com.increase.api.core.UnwrapWebhookParams
 import com.increase.api.core.checkRequired
 import com.increase.api.core.handlers.errorBodyHandler
 import com.increase.api.core.handlers.errorHandler
@@ -17,12 +18,15 @@ import com.increase.api.core.http.HttpResponseFor
 import com.increase.api.core.http.parseable
 import com.increase.api.core.prepare
 import com.increase.api.errors.IncreaseInvalidDataException
+import com.increase.api.errors.IncreaseWebhookException
 import com.increase.api.models.events.Event
 import com.increase.api.models.events.EventListPage
 import com.increase.api.models.events.EventListPageResponse
 import com.increase.api.models.events.EventListParams
 import com.increase.api.models.events.EventRetrieveParams
 import com.increase.api.models.events.UnwrapWebhookEvent
+import com.standardwebhooks.Webhook
+import com.standardwebhooks.exceptions.WebhookVerificationException
 import java.util.function.Consumer
 import kotlin.jvm.optionals.getOrNull
 
@@ -46,18 +50,35 @@ class EventServiceImpl internal constructor(private val clientOptions: ClientOpt
         // get /events
         withRawResponse().list(params, requestOptions).parse()
 
-    /**
-     * Unwraps a webhook event from its JSON representation.
-     *
-     * @throws IncreaseInvalidDataException if the body could not be parsed.
-     */
     override fun unwrap(body: String): UnwrapWebhookEvent =
         try {
             clientOptions.jsonMapper.readValue(body, jacksonTypeRef<UnwrapWebhookEvent>())
         } catch (e: Exception) {
             throw IncreaseInvalidDataException("Error parsing body", e)
         }
 
+    override fun unwrap(unwrapParams: UnwrapWebhookParams): UnwrapWebhookEvent {
+        val headers = unwrapParams.headers().getOrNull()
+        if (headers != null) {
+            try {
+                val webhookSecret =
+                    checkRequired(
+                        "webhookSecret",
+                        unwrapParams.secret().getOrNull()
+                            ?: clientOptions.webhookSecret().getOrNull(),
+                    )
+                val headersMap =
+                    headers.names().associateWith { name -> headers.values(name) }.toMap()
+
+                val webhook = Webhook(webhookSecret)
+                webhook.verify(unwrapParams.body(), headersMap)
+            } catch (e: WebhookVerificationException) {
+                throw IncreaseWebhookException("Could not verify webhook event signature", e)
+            }
+        }
+        return unwrap(unwrapParams.body())
+    }
+
     class WithRawResponseImpl internal constructor(private val clientOptions: ClientOptions) :
         EventService.WithRawResponse {
 

increase-java-core/src/test/kotlin/com/increase/api/services/async/EventServiceAsyncTest.kt

@@ -4,7 +4,13 @@ package com.increase.api.services.async
 
 import com.increase.api.TestServerExtension
 import com.increase.api.client.okhttp.IncreaseOkHttpClientAsync
+import com.increase.api.core.UnwrapWebhookParams
+import com.increase.api.core.http.Headers
+import com.increase.api.errors.IncreaseWebhookException
+import com.standardwebhooks.Webhook
+import java.time.Instant
 import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
 import org.junit.jupiter.api.extension.ExtendWith
 
 @ExtendWith(TestServerExtension::class)
@@ -39,4 +45,84 @@ internal class EventServiceAsyncTest {
         val page = pageFuture.get()
         page.response().validate()
     }
+
+    @Test
+    fun unwrap() {
+        val client =
+            IncreaseOkHttpClientAsync.builder()
+                .baseUrl(TestServerExtension.BASE_URL)
+                .apiKey("My API Key")
+                .build()
+        val eventServiceAsync = client.events()
+
+        val payload =
+            "{\"id\":\"event_001dzz0r20rzr4zrhrr1364hy80\",\"associated_object_id\":\"account_in71c4amph0vgo2qllky\",\"associated_object_type\":\"account\",\"category\":\"account.created\",\"created_at\":\"2020-01-31T23:59:59Z\",\"type\":\"event\"}"
+        val webhookSecret = "whsec_c2VjcmV0Cg=="
+        val messageId = "1"
+        val timestampSeconds = Instant.now().epochSecond
+        val webhook = Webhook(webhookSecret)
+        val signature = webhook.sign(messageId, timestampSeconds, payload)
+        val headers =
+            Headers.builder()
+                .putAll(
+                    mapOf(
+                        "webhook-signature" to listOf(signature),
+                        "webhook-id" to listOf(messageId),
+                        "webhook-timestamp" to listOf(timestampSeconds.toString()),
+                    )
+                )
+                .build()
+
+        eventServiceAsync.unwrap(payload).validate()
+
+        // Wrong key should throw
+        assertThrows<IncreaseWebhookException> {
+            val wrongKey = "whsec_aaaaaaaaaa"
+            eventServiceAsync.unwrap(
+                UnwrapWebhookParams.builder()
+                    .body(payload)
+                    .headers(headers)
+                    .secret(wrongKey)
+                    .build()
+            )
+        }
+
+        // Bad signature should throw
+        assertThrows<IncreaseWebhookException> {
+            val badSig = webhook.sign(messageId, timestampSeconds, "some other payload")
+            val badHeaders =
+                headers.toBuilder().replace("webhook-signature", listOf(badSig)).build()
+            eventServiceAsync.unwrap(
+                UnwrapWebhookParams.builder()
+                    .body(payload)
+                    .headers(badHeaders)
+                    .secret(webhookSecret)
+                    .build()
+            )
+        }
+
+        // Old timestamp should throw
+        assertThrows<IncreaseWebhookException> {
+            val oldHeaders = headers.toBuilder().replace("webhook-timestamp", listOf("5")).build()
+            eventServiceAsync.unwrap(
+                UnwrapWebhookParams.builder()
+                    .body(payload)
+                    .headers(oldHeaders)
+                    .secret(webhookSecret)
+                    .build()
+            )
+        }
+
+        // Wrong message ID should throw
+        assertThrows<IncreaseWebhookException> {
+            val wrongIdHeaders = headers.toBuilder().replace("webhook-id", listOf("wrong")).build()
+            eventServiceAsync.unwrap(
+                UnwrapWebhookParams.builder()
+                    .body(payload)
+                    .headers(wrongIdHeaders)
+                    .secret(webhookSecret)
+                    .build()
+            )
+        }
+    }
 }