Package ai.extend.wrapper.webhooks

Class Webhooks

java.lang.Object

ai.extend.wrapper.webhooks.Webhooks

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class Webhooks
extends java.lang.Object
implements java.io.Closeable

Utility class for verifying and parsing webhook events.

This class provides methods to verify webhook signatures, parse webhook bodies, and handle signed URL payloads.

Basic Usage

 Webhooks webhooks = new Webhooks();

 // Verify and parse a webhook (throws if signed URL received)
 WebhookEvent event = webhooks.verifyAndParse(body, headers, signingSecret);
 event.visit(new WebhookEvent.Visitor<Void>() { ... });
 

Handling Signed URLs

 RawWebhookEvent raw = webhooks.verifyAndParseWithOptions(body, headers, signingSecret,
     VerifyAndParseOptions.builder().allowSignedUrl(true).build());
 if (raw.isSignedUrlEvent()) {
     WebhookEvent fullEvent = webhooks.fetchSignedPayload(raw.getSignedUrlEvent());
 } else {
     WebhookEvent event = raw.getEvent();
 }
 

Constructor Summary

Constructors

Constructor	Description
Webhooks()
Webhooks(okhttp3.OkHttpClient httpClient)	Creates a new Webhooks instance with a custom OkHttpClient.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes the underlying HTTP client if it was created by this instance.
WebhookEvent	fetchSignedPayload(WebhookEventWithSignedUrl event)	Fetches the full payload from a signed URL event.
RawWebhookEvent	parse(java.lang.String body)	Parses the webhook body without verification.
boolean	verify(java.lang.String body, java.util.Map<java.lang.String,java.lang.String> headers, java.lang.String signingSecret)	Verifies the webhook signature without parsing.
boolean	verify(java.lang.String body, java.util.Map<java.lang.String,java.lang.String> headers, java.lang.String signingSecret, VerifyOptions options)	Verifies the webhook signature without parsing.
WebhookEvent	verifyAndParse(java.lang.String body, java.util.Map<java.lang.String,java.lang.String> headers, java.lang.String signingSecret)	Verifies the webhook signature and parses the event.
RawWebhookEvent	verifyAndParseWithOptions(java.lang.String body, java.util.Map<java.lang.String,java.lang.String> headers, java.lang.String signingSecret, VerifyAndParseOptions options)	Verifies the webhook signature and parses the event with options.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Webhooks

public Webhooks()

Webhooks

public Webhooks(okhttp3.OkHttpClient httpClient)

Creates a new Webhooks instance with a custom OkHttpClient.

Use this constructor to customize timeouts, proxy settings, or connection pool configuration. The provided client will not be closed when close() is called.

Parameters:

httpClient - The OkHttpClient to use for fetching signed URL payloads

Method Detail

close

public void close()

Closes the underlying HTTP client if it was created by this instance.

If a custom OkHttpClient was provided via Webhooks(OkHttpClient), this method does nothing (the caller is responsible for closing their client).

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

verifyAndParse

public WebhookEvent verifyAndParse(java.lang.String body,
                                   java.util.Map<java.lang.String,java.lang.String> headers,
                                   java.lang.String signingSecret)
                            throws WebhookSignatureVerificationError,
                                   SignedUrlNotAllowedError

Verifies the webhook signature and parses the event.

Throws SignedUrlNotAllowedError if a signed URL payload is received. Use verifyAndParseWithOptions(java.lang.String, java.util.Map<java.lang.String, java.lang.String>, java.lang.String, ai.extend.wrapper.webhooks.VerifyAndParseOptions) with allowSignedUrl=true to handle signed URL payloads.

Parameters:

body - The raw request body as a string

headers - The request headers (case-insensitive lookup supported)

signingSecret - The webhook signing secret from the Extend dashboard

Returns:

The parsed typed webhook event

Throws:

WebhookSignatureVerificationError - if signature verification fails

SignedUrlNotAllowedError - if a signed URL payload is received

verifyAndParseWithOptions

public RawWebhookEvent verifyAndParseWithOptions(java.lang.String body,
                                                 java.util.Map<java.lang.String,java.lang.String> headers,
                                                 java.lang.String signingSecret,
                                                 VerifyAndParseOptions options)
                                          throws WebhookSignatureVerificationError,
                                                 SignedUrlNotAllowedError

Verifies the webhook signature and parses the event with options.

Returns a RawWebhookEvent (union of typed event or signed URL event), matching the TypeScript and Python SDKs. Use RawWebhookEvent.isSignedUrlEvent() to narrow, then RawWebhookEvent.getEvent() or RawWebhookEvent.getSignedUrlEvent().

Parameters:

body - The raw request body as a string

headers - The request headers (case-insensitive lookup supported)

signingSecret - The webhook signing secret from the Extend dashboard

options - Verification and parsing options

Returns:

A raw webhook event (either normal or signed URL)

Throws:

WebhookSignatureVerificationError - if signature verification fails

SignedUrlNotAllowedError - if signed URL received without allowSignedUrl=true

verify

public boolean verify(java.lang.String body,
                      java.util.Map<java.lang.String,java.lang.String> headers,
                      java.lang.String signingSecret)

Verifies the webhook signature without parsing.

Parameters:

body - The raw request body as a string

headers - The request headers

signingSecret - The webhook signing secret

Returns:

true if the signature is valid, false otherwise

verify

public boolean verify(java.lang.String body,
                      java.util.Map<java.lang.String,java.lang.String> headers,
                      java.lang.String signingSecret,
                      VerifyOptions options)

Verifies the webhook signature without parsing.

Parameters:

body - The raw request body as a string

headers - The request headers

signingSecret - The webhook signing secret

options - Verification options

Returns:

true if the signature is valid, false otherwise

parse

public RawWebhookEvent parse(java.lang.String body)

Parses the webhook body without verification.

Warning: Only use this after separately verifying the signature with verify(java.lang.String, java.util.Map<java.lang.String, java.lang.String>, java.lang.String).

Parameters:

body - The raw request body as a string

Returns:

A raw webhook event (either normal or signed URL)

fetchSignedPayload

public WebhookEvent fetchSignedPayload(WebhookEventWithSignedUrl event)
                                throws WebhookPayloadFetchError

Fetches the full payload from a signed URL event.

Parameters:

event - The webhook event with a signed URL payload

Returns:

The full typed webhook event with resolved payload

Throws:

WebhookPayloadFetchError - if the fetch fails