Comprehensive Guide to the Webhook API

The Webhook API offers a suite of endpoints for effective webhook management. This guide provides detailed explanations of each endpoint, enriched with examples and real-world application scenarios.

Introduction to Webhooks

What is a Webhook?

A webhook is an automated communication method used in web development. It allows applications to automatically send real-time information to other applications when a specific event occurs. Unlike traditional API calls, which require a client to poll for data regularly, webhooks deliver data as it happens, effectively "pushing" data to the recipient.

Why Use Webhooks?

Webhooks offer several advantages, especially when compared to polling for changes:

• Efficiency: Webhooks provide data in real-time. As soon as an event occurs (like an update or a new entry), the information is immediately sent to the specified URL. This contrasts with polling, where an application must frequently check for updates, consuming more resources and often leading to delays in data reception.
• Reduced Server Load: Polling involves making repeated requests at regular intervals, which can be resource-intensive, especially for servers handling multiple clients. Webhooks eliminate this by sending data only when there's something new, significantly reducing the load on both the client and server systems.
• Improved Responsiveness: Applications using webhooks can react instantly to changes, leading to faster and more dynamic responses. This is particularly beneficial in scenarios requiring timely actions, such as triggering automated workflows or sending instant notifications.

Entities and Actions

The Webhook API supports a variety of entities and actions, each representing a specific type of event that can trigger a webhook. The following table provides an overview of the supported entities and their corresponding actions:

	Create	Update	Delete	Cancel	Activate	Complete	Lock	Reset Password	Obfuscate
Product	X	X	X
Brand	X	X	X
Catergory	X	X	X
Supplier	X	X	X
PageWidget		X	X
Customer	X	X	X					X	X
Order	X	X		X	X	X	X
Order Capture	X
Order Refund	X

Refer to the Webhook API Reference for detailed information about each entity and its supported actions.

Endpoints Overview

1. GET a Webhook: Retrieve details of a specific webhook.
2. POST a New Webhook: Create a new webhook.
3. PUT to Update Webhook: Update an existing webhook.
4. DELETE a Webhook: Remove a webhook.
5. GET All Webhooks: Retrieve a list of all webhooks.

Create a new Webhook

Create a new webhook by specifying detailed attributes. This endpoint allows for the configuration of various aspects of a webhook.

Request

POST /API/Webhook

Attributes

• Entity: The type of entity to which the webhook subscribes. Possible values include Product, Brand, Category, Supplier, Order, Capture, Refund, PageWidget, Customer.
• Name: A descriptive name for the webhook.
• Description: Detailed information about the purpose and functionality of the webhook.
• Actions: A comma-separated list of actions the webhook will respond to. Each entity type supports different actions. For example, Product, Brand, Category, Supplier may support create, update, delete, whereas Order might support actions like create, update, cancel.
• Method: The HTTP method (e.g., POST, GET) used by the webhook.
• Url: The endpoint URL where the webhook will send its payload.
• Body: The content or payload that will be sent with the webhook. This is typically in JSON format.
• Headers: Any additional HTTP headers that need to be sent with the webhook, such as content type or authentication tokens.
• Retry: A boolean indicating whether the webhook should automatically retry upon failure. If set to true, retries are attempted up to 3 times with a 10 minute interval.

Utilizing Placeholders in Webhook Url and Body

Placeholders offer a dynamic and flexible way to customize the content of webhook URLs and bodies. They are particularly useful for tailoring the webhook's payload to specific events or data points. Below is an explanation of how to effectively use placeholders in your Webhook API.

Understanding Placeholders

Placeholders are variables enclosed within double curly braces {{ }}. They are replaced with actual values when the webhook is triggered. Here's a list of available placeholders and their contexts:

Always Available Placeholders:

• {{entity}}: Represents the entity type (e.g., Product, Brand, Category).
• {{action}}: Indicates the action performed (e.g., create, update, delete).
• {{account}}: Usually the name of your webshop or account.
• {{environment}}: The environment where the action occurred, like prod, dev, qa.
• {{id}}: Can be a single ID or a comma-separated list of IDs relevant to the event.

Partially Available Placeholders:

• {{paymentName}}: Name of the payment method, applicable only for capture and refund entities.
• {{channelName}}: Name of the channel (website), applicable for capture, refund, and some other specific scenarios.
• {{channelUrl}}: URL of the channel (website), mainly used for password reset events.
• {{resetKey}}: Key for password reset, relevant only for password reset actions.

How to Use Placeholders

Placeholders can be inserted into the URL and body of the webhook configuration. When an event occurs, these placeholders are replaced with actual data related to that event.

Important Considerations

Not all placeholders are available for all combinations of entities and actions. Ensure that the placeholders you use are relevant to the webhook's entity and action. Irrelevant placeholders for a given entity-action combination will remain unchanged in the data being transmitted.

Idempotency

When creating and configuring webhooks, it's important to understand the concept of idempotency, especially in the context of webhook retries.

Each webhook request includes a unique HTTP header called x-Idempotency-Key. This key serves as an identifier for each specific webhook event. The key remains the same for all retry attempts of the same webhook event.

The primary purpose of the x-Idempotency-Key is to enable the receiving system to identify and handle duplicate webhook events. This is particularly useful in scenarios where a webhook might be sent multiple times due to retries.

When a webhook is retried (for instance, due to a failure in the initial delivery), it will carry the same idempotency key as the original attempt. The receiving system should use this key to recognize and filter out events that have already been processed, thus preventing duplicate processing of the same webhook event.

Alongside the x-Idempotency-Key, webhooks include another header: x-Timestamp. This header provides the exact time when the webhook event was generated. The timestamp is crucial for determining the freshness of the webhook event, especially in scenarios where network delays or retries are involved.

cURL Example

curl -X POST "https://mgmtapi.geins.io/API/Webhook" \
     -H "Content-Type: application/json" \
     -H "X-Apikey: your_api_key_here" \
     -u "username:password" \
     -d '{
           "Entity": "Order",
           "Name": "Order Notification",
           "Description": "Webhook for order updates",
           "Actions": "update,cancel",
           "Method": "POST",
           "Url": "https://yourwebhookendpoint.com/notifications/{{entity}}?action={{action}}",
           "Body": "{\"order_id\":\"{{id}}\"}",
           "Headers": "Content-Type: application/json",
           "Retry": true
         }'

Usage Scenario

For instance, to create a webhook that triggers on order updates and cancellations, specify Order as the entity and include update and cancel in the actions. The webhook could then send notifications to a specified URL with details about the order whenever its status changes.

GET a Webhook

Retrieve detailed information about a specific webhook by its unique identifier (ID). This endpoint is crucial for checking the current configuration and status of a registered webhook.

Request

GET /API/Webhook/{webhookId}

Attributes

• webhookId: The unique identifier of the webhook you want to retrieve. This is a GUID that uniquely identifies each webhook in the system.

cURL Example

curl -X GET "https://mgmtapi.geins.io/API/Webhook/123e4567-e89b-12d3-a456-426614174000" \
     -H "Accept: application/json" \
     -H "X-Apikey: your_api_key_here" \
     -u "username:password"

Usage Scenario

Suppose you have set up a webhook to track changes in customer data. Over time, you might need to verify its configuration, such as the URL it targets or the specific customer actions it listens for. Using this endpoint, you can fetch the current settings of your webhook by providing its unique ID.

DELETE a Webhook

Remove a specific webhook from the system by using its unique identifier (ID).

Request

DELETE /API/Webhook/{webhookId}

Attributes

• webhookId: The unique GUID identifying the webhook to be deleted. This ID should correspond to the webhook that is no longer required.

cURL Example

curl -X DELETE "https://mgmtapi.geins.io/API/Webhook/123e4567-e89b-12d3-a456-426614174000" \
     -H "X-Apikey: your_api_key_here" \
     -u "username:password"

Usage Scenario

Consider a scenario where a webhook set up for monitoring product inventory levels is no longer needed. In such cases, it's important to clean up and remove the redundant webhook to prevent unnecessary data traffic and to keep the webhook management system organized.

Update a Webhook

Update the configuration of an existing webhook. Use this endpoint to update or correct previously set configurations.

Request

PUT /API/Webhook/{webhookId}

Attributes

Url:

• webhookId: The unique identifier (GUID) of the webhook to be updated.

Body:

• Entity: Update the entity type for the webhook. Possible values include Product, Brand, Category, Supplier, etc.
• Name: A new name for the webhook.
• Description: Updated information describing the webhook's purpose.
• Actions: Modify the list of actions the webhook listens to, such as create, update, delete.
• Method: Change the HTTP method used by the webhook.
• Url: Update the endpoint URL where the webhook sends data.
• Body: Modify the content or payload sent with the webhook.
• Headers: Update any additional HTTP headers sent with the webhook.
• Retry: Change the retry behavior on failure.

cURL Example

curl -X PUT "https://mgmtapi.geins.io/API/Webhook/123e4567-e89b-12d3-a456-426614174000" \
     -H "Content-Type: application/json" \
     -H "X-Apikey: your_api_key_here" \
     -u "username:password" \
     -d '{
           "Entity": "Order",
           "Name": "Order Creation and Update Webhook",
           "Description": "Webhook for order creation and update events",
           "Actions": "create, update",
           "Method": "POST",
           "Url": "https://yourwebhookendpoint.com/{{entity}}/{{action}}/{{id}}",
           "Body": "{\"entity\":\"{{entity}}\", \"action\":\"{{action}}\", \"orderId\":\"{{id}}\"}",
           "Headers": "Content-Type: application/json",
           "Retry": true
         }'

Usage Scenario

Imagine you have a webhook configured for notifying product updates. If you decide to change the notification mechanism – for instance, switching the URL to a new endpoint or changing the types of product actions to monitor (e.g., from just update to both create and update) – you can use this endpoint to make those changes.

GET All Webhooks

Retrieve a list of all registered webhooks in the system.

Request

GET /API/Webhook/List

Attributes

• This endpoint does not require any specific attributes, as it is designed to fetch a list of all webhooks without filters.

cURL Example

curl -X GET "https://mgmtapi.geins.io/API/Webhook/List" \
     -H "Accept: application/json" \
     -H "X-Apikey: your_api_key_here" \
     -u "username:password"

Usage Scenario

Consider a scenario where your system has numerous webhooks set up across various departments or functionalities, such as order processing, customer management, and inventory updates. By using this endpoint, you can quickly gather a list of all the webhooks, along with their configurations.

Troubleshooting Common Issues

When working with the Webhook API, it's important to understand how to interpret and respond to various error codes. This section covers common issues and their corresponding HTTP status codes to help you troubleshoot effectively.

Handling 404 Not Found Errors

The 404 Not Found status code indicates that the requested resource (e.g., a specific webhook) does not exist. This can occur in several scenarios:

• Fetching a Non-existent Webhook: When you try to retrieve details of a webhook using an ID that does not correspond to any existing webhook, the API responds with a 404 error.
• Deleting a Non-existent Webhook: Attempting to delete a webhook that cannot be found in the system will also result in a 404 response.
• Updating a Non-existent Webhook: Similarly, if you try to update a webhook using an ID that is not in the system, you will receive a 404 error.

Dealing with 400 Bad Request Errors

A 400 Bad Request status code typically indicates that there's something wrong with the client's request. This could be due to malformed request syntax, invalid request message parameters. Common causes include:

• Errors in Input Format: If the data sent in the request body (for example, while creating or updating a webhook) is incorrectly formatted, the API will respond with a 400 error.
• Invalid Data: Sending data that doesn't conform to the expected schema or data types can also trigger a 400 error.

Important Note When Creating Webhooks

• Matching Actions with Entity Types: When creating a new webhook, it's crucial to ensure that the actions you specify are supported for the chosen entity type. Each entity type has a specific set of actions it supports. Sending unsupported actions for an entity will result in a bad request error. Make sure to refer to the API documentation to understand which actions are applicable for each entity type.

Next Steps

Ready-to-Use Webhook Templates

The "Templates" section offers ready-to-use webhook notification examples for popular platforms like Microsoft Teams Slack and Mailchimp. These templates are designed to help you quickly set up effective notifications, ensuring seamless integration and communication within your team.

• Microsoft Teams Notifications
• Slack Notifications
• Send emails with Mailchimp