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). Webhooks are commonly used to notify external systems about state changes or asynchronous task results.Common Use Cases#
| Use Case | Description |
|---|
| Payment Notifications | Payment platform sends notification when an order is successfully paid |
| Authentication Updates | Third-party login service updates login status |
| Asynchronous Task Results | Background tasks send results upon completion |
| Event Triggers | System notifies external services when specific events occur |
Key Difference from Regular Endpoints#
Although technically a Webhook is just an HTTP endpoint, it differs in how it's used:Webhook: The system initiates the call to the external URL
Regular Endpoint: The client sends the request to the system
Creating a Webhook Endpoint#
1
In your Apidog project, click the
"+" icon in the left sidebar and choose
"New Other Protocol APIs" β
"Webhook".
2
After creating the Webhook, fill out the following fields in the editor:
| Field | Description |
|---|
| Request Method | Typically POST |
| Webhook Name | Appears in API documentation and OpenAPI export (e.g., order) |
| Debug URL | Optional. Actual URL used for sending test requests (for testing only, not included in documentation) |
| Other Info | Request body, headers, and other configuration |
3
Click "Save" once 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.1.
Enter your Webhook URL into the Debug URL field
2.
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.
webhooks field, which is different from the paths field of regular endpoints.FAQs#
According to the OpenAPI 3.1 specification:
Regular endpoints are defined under the paths field
Webhook endpoints are defined under the webhooks field
Regular endpoints are called by external clients to perform actions or retrieve data
Webhooks are triggered by the system to notify external services
/orders is a regular endpoint used by clients
orderPaid is a Webhook triggered by the system when an order is paid successfully
