webhook.md

description
This page contains the technical details of the Webhook entrypoint plugin

Webhook

{% hint style="warning" %} This feature requires Gravitee's Enterprise Edition. {% endhint %}

Overview

This Advanced version of the Webhook plugin adds enterprise features to the OSS version of the Webhook entrypoint, including Dead Letter Queue and secured callback. Refer to the following sections for additional details.

• Quality of Service
• Compatibility matrix
• Entrypoint identifier
• Entrypoint configuration

Quality of Service

The Advanced version of the Webhook plugin offers improved QoS.

QoS	Delivery	Description
None	Unwarranted	Performance matters over delivery guarantee
Auto	0 or n	Performance matters over delivery guarantee
At-Most-Once	0 or 1	Delivery guarantee matters over performance
At-Least-Once	1 or n	Delivery guarantee matters over performance

Compatibility matrix

Plugin version	APIM version
1.x	3.21.x

Entrypoint identifier

To use this Advanced version of the plugin, either:

• Declare the following webhook-advanced identifier while configuring your API entrypoints
• Simply update your existing API, due to the compatibility of the Advanced and OSS configurations

Entrypoint configuration

When creating the Webhook subscription, the following configuration is provided:

{
    "configuration": {
        "entrypointId": "webhook-advanced",
        "callbackUrl": "https://example.com"
    }
}

HTTP options

The underlying HTTP client that performs the calls to the Webhook URL can be tuned via the following parameters.

Attributes	Default	Mandatory	Description
connectTimeout	3000	Yes	Maximum time to connect to the backend in milliseconds.
readTimeout	10000	Yes	Maximum time given to the backend to complete the request (including response) in milliseconds.
idleTimeout	60000	Yes	Maximum time a connection will stay in the pool without being used in milliseconds. Once the timeout has elapsed, the unused connection will be closed, freeing the associated resources.
maxConcurrentConnections	5	Yes	Maximum pool size for connections. This represents the maximum number of concurrent requests. Max value is 20. Value is automatically set to 1 when using QoS AT_LEAST_ONCE or AT_MOST_ONCE to ensure message delivery.

Dead Letter Queue

Dead Letter Queue (DLQ) is the ability to push undelivered messages to an external storage. When configuring DLQ with Webhook, you can redirect all messages rejected by the Webhook to another location, such as a Kafka topic.

By default, without DLQ, any error returned by the Webhook will stop message consumption.

Enabling DLQ requires declaring another endpoint that will be used to configure the dlq section of the Webhook entrypoint definition:

{
    "type": "webhook-advanced",
    "dlq": {
        "endpoint": "dlq-endpoint"
    },
    "configuration": {}
}

The endpoint used for the DLQ:

• Must support PUBLISH mode
• Should be based on a broker capable of persisting messages, e.g., Kafka

Once configured and deployed, any message rejected by the Webhook with a 4xx error response will be automatically sent to the DLQ endpoint and message consumption will resume.

Secured callbacks

Security information can be provided when creating the subscription. Examples of the currently supported authentication protocols are shown below.

{% tabs %} {% tab title="Basic" %}

{
    "configuration": {
        "entrypointId": "webhook-advanced",
        "callbackUrl": "https://example.com",
        "auth": {
            "type": "basic",
            "basic": {
                "username": "username",
                "password": "a-very-secured-password"
            }
        }
    }
}

{% endtab %}

{% tab title="Token JWT" %}

{
    "configuration": {
        "entrypointId": "webhook-advanced",
        "callbackUrl": "https://example.com",
        "auth": {
            "type": "token",
            "token": {
                "value": "eyJraWQiOiJk..."
            }
        }
    }
}

{% endtab %}

{% tab title="OAuth2" %}

{
    "configuration": {
        "entrypointId": "webhook-advanced",
        "callbackUrl": "https://example.com",
        "auth": {
            "type": "oauth2",
            "oauth2": {
                "endpoint": "https://auth.gravitee.io/my-domain/oauth/token",
                "clientId": "a-client-id",
                "clientSecret": "a-client-secret",
                "scopes": ["roles"]
            }
        }
    }
}

{% endtab %} {% endtabs %}