Webhook

A Webhook is an HTTP endpoint used to receive event notifications. When a specific event occurs, the system actively sends an HTTP request to a predefined URL (the Webhook URL). It's commonly used to notify external systems about state changes or asynchronous task results.

Common Use Cases:

A payment platform sends a notification when an order is successfully paid.

A third-party login service updates login status.

Asynchronous tasks send results upon completion.

Although technically a Webhook is just an HTTP endpoint, it differs in how it's used: the system initiates the call to the external URL, whereas in typical endpoints, the client sends the request to the system.

Creating a Webhook Endpoint

In your Apidog project, click the + icon in the left sidebar and choose "New Other Protocol APls" > "Webhook".

After creating the Webhook, fill out the following fields in the editor:

Request Method: TypicallyPOST.

Webhook name: This will appear in the API documentation and OpenAPI export, e.g., order.

Debug URL(optional): The actual URL used for sending test requests. Note: This is for testing purposes only and will not be included in documentation.

Other Info: Such as the request body.

ClickSaveonce you've completed all required fields.

Debugging a Webhook Endpoint

Webhook debugging simulates an event trigger to verify whether the external service correctly receives the request.

Just enter your Webhook URL into the Debug URL field, then click Send to simulate a Webhook call.

Webhook Documentation

Webhook documentation includes details such as the Webhook name, request method, and request body. This makes it easier for users to understand what kind of data will be sent when a certain event occurs.

The Debug URL will not be included in the documentation or OpenAPI export — it's only for internal testing.

In the exported OpenAPI file, Webhook endpoints are listed under thewebhooksfield, which is different from the paths field of the regular endpoints.

FAQs

Why define Webhooks separately in documentation?

According to the OpenAPI 3.1 specification:

Regular endpoints are defined under thepathsfield

Webhook endpoints are defined under thewebhooksfield

This clear separation ensures:

Regular endpoints are called by external clients to perform actions or retrieve data

Webhooks are triggered by the system to notify external services

In Apidog, Webhooks are treated as a distinct endpoint type to accurately reflect this directional difference and ensure proper formatting in OpenAPI exports.

Example:

/ordersis a regular endpoint used by clients.

orderPaidis a Webhook triggered by the system when an order is paid successfully.

Is a Webhook just a regular endpoint?

Will the Debug URL show up in my API documentation?

Creating a Webhook Endpoint#

Debugging a Webhook Endpoint#

Webhook Documentation#

FAQs#

Creating a Webhook Endpoint

Debugging a Webhook Endpoint

Webhook Documentation

FAQs