Webhook Java SDK Integration

To integrate using the Java SDK please use the latest version available on Maven Central.

Pre-Requisite

Get a Yapily Access Token

Add SDK Dependency

Add the SDK as a dependency to your project

Maven

Copy

Copied

 <dependency>
    <groupId>com.yapily.sdk.webhook</groupId>
    <artifactId>webhook-sdk</artifactId>
    <version>${yapily.webhook.sdk.version}</version>
</dependency>

Gradle

Copy

Copied

implementation group: 'com.yapily.sdk.webhook', name: 'webhook-sdk', version: $yapilyWebhookSdkVersion

Create Webhook Client

Copy

Copied

var webhookClient = WebhookClient.newClient();

Retrieve Event Categories

This call will give you all available categories for possible for registering a webhook

Copy

Copied

GetAllCategoryResponse response = webhookClient.getWebhookEventsCategories(yapilyAccessToken);

Registering a Webhook

Copy

Copied

CreateWebhookResponse response = WebhookClient.registerWebhook(createRequestPayload, yapilyAccessToken);

Extracting webhook secret

using the response from registering a webhook we can extract the webhook secret

Copy

Copied

var webhookSecret = response.data().webhookSecret();

note

This is the only API call that would display the webhook secret, you will not be able to retrieve the secret using the API after registration call, please store it if you want to use the webhook signature validation feature

Retrieve registered webhooks

Copy

Copied

RetrieveAllWebhooksResponse response = webhookClient.retrieveAllWebhooks(yapilyAccessToken);

Resetting webhook secret

Copy

Copied

ResetWebhookSecretResponse response = webhookClient.webhookSecretReset(webhookId, yapilyAccessToken);

Deleting a webhook

Copy

Copied

RemoveWebhookResponse response = webhookClient.removeWebhook(webhookId, yapilyAccessToken);

Validating an event signature

All payloads are being signed using HMAC algorithm HmacSHA256, when receiving an event do the following:

Use the saved webhookSecret provided to you during webhook registration or key rotation to generate the hash
The payload received should be read and processed in String format
Use the SDK to validate the signature and map the event

Copy

Copied

 try {
    EventHandler eventHandler = new EventHandler(webhookSecret)
    WebhookEvent event = eventHandler.process(eventPaylodString, requestHeadersMap);
} catch(InvalidInputException e) {
    // thrown when required headers are missing
} catch(InvalidSignatureException e) {
    // thrown when signature validation fails
}

note

Do not map the event to any structure that may affect the order or structure of the payload before generating the signature, read the event as a string and pass it to the SDK