Webhooks

API Reference

The Webhook API provides endpoints for creating, retrieving, updating, and deleting webhooks. This page covers all available operations with examples.

Base URL

https://mgmtapi.geins.io/API/Webhook

Authentication

All webhook endpoints require:

X-ApiKey header with your Management API key
Basic Auth (username:password)

Create a Webhook

Request

POST /API/Webhook

Request Body

Field	Type	Required	Description
`Entity`	string	Yes	Entity type to monitor. See Entities and Actions
`Name`	string	Yes	Descriptive name for the webhook
`Description`	string	No	Detailed purpose and functionality description
`Actions`	string	Yes	Comma-separated list of actions (e.g., `create,update,delete`)
`Method`	string	Yes	HTTP method (typically `POST` or `GET`)
`Url`	string	Yes	Target endpoint URL (supports placeholders)
`Body`	string	No	Request payload (supports placeholders)
`Headers`	string	No	Additional HTTP headers (e.g., `Content-Type: application/json`)
`Retry`	boolean	No	Enable automatic retries on failure (default: `false`)

cURL Example

curl -X POST "https://mgmtapi.geins.io/API/Webhook" \
     -H "Content-Type: application/json" \
     -H "X-ApiKey: {MGMT_API_KEY}" \
     -u "{MGMT_USERNAME}:{MGMT_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
         }'

Response

Success (200 OK):

{
    "Resource": "a062696f-26c8-49ed-8067-697378d60b75",
    "Message": "Success.",
    "Details": null
}

Get a Webhook

Retrieve details about a specific webhook using its unique ID.

Request

GET /API/Webhook/{webhookId}

Path Parameters

Parameter	Type	Required	Description
`webhookId`	GUID	Yes	Unique identifier of the webhook

cURL Example

curl -X GET "https://mgmtapi.geins.io/API/Webhook/123e4567-e89b-12d3-a456-426614174000" \
     -H "Accept: application/json" \
     -H "X-ApiKey: {MGMT_API_KEY}" \
     -u "{MGMT_USERNAME}:{MGMT_PASSWORD}" \

Response

Success (200 OK):

{
    "Resource": {
        "Id": "123e4567-e89b-12d3-a456-426614174000",
        "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
    },
    "Message": "Success.",
    "Details": null
}

Update a Webhook

Modify an existing webhook's configuration.

Request

PUT /API/Webhook/{webhookId}

Path Parameters

Parameter	Type	Required	Description
`webhookId`	GUID	Yes	Unique identifier of the webhook to update

Request Body

Same fields as Create a Webhook. All fields can be updated.

cURL Example

curl -X PUT "https://mgmtapi.geins.io/API/Webhook/123e4567-e89b-12d3-a456-426614174000" \
     -H "Content-Type: application/json" \
     -H "X-ApiKey: {MGMT_API_KEY}" \
     -u "{MGMT_USERNAME}:{MGMT_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
         }'

Response

Success (200 OK):

{
    "Message": "Success.",
    "Details": null
}

Delete a Webhook

Remove a webhook from the system.

Request

DELETE /API/Webhook/{webhookId}

Path Parameters

Parameter	Type	Required	Description
`webhookId`	GUID	Yes	Unique identifier of the webhook to delete

cURL Example

curl -X DELETE "https://mgmtapi.geins.io/API/Webhook/123e4567-e89b-12d3-a456-426614174000" \
     -H "X-ApiKey: {MGMT_API_KEY}" \
     -u "{MGMT_USERNAME}:{MGMT_PASSWORD}" \

Response

Success (200 OK):

{
    "Message": "Success.",
    "Details": null
}

List All Webhooks

Retrieve all registered webhooks for your account.

Request

GET /API/Webhook/List

Parameters

None. Returns all webhooks without filtering.

cURL Example

curl -X GET "https://mgmtapi.geins.io/API/Webhook/List" \
     -H "Accept: application/json" \
     -H "X-ApiKey: {MGMT_API_KEY}" \
     -u "{MGMT_USERNAME}:{MGMT_PASSWORD}" \

Response

Success (200 OK):

{
    "Resource": [
        {
            "Id": "123e4567-e89b-12d3-a456-426614174000",
            "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
        },
        {
            "Id": "987fcdeb-51a2-43f7-b829-123456789abc",
            "Entity": "Product",
            "Name": "Product Price Monitor",
            "Description": "Monitor product price changes",
            "Actions": "update",
            "Method": "POST",
            "Url": "https://analytics.example.com/product-changes",
            "Body": null,
            "Headers": "Content-Type: application/json",
            "Retry": false
        }
    ],
    "Message": "Success.",
    "Details": null
}

Error Handling

Common HTTP status codes returned by the Webhook API:

Status Code	Description	Common Cause
`200 OK`	Request successful	GET, PUT operations succeeded
`201 Created`	Webhook created successfully	POST operation succeeded
`204 No Content`	Webhook deleted successfully	DELETE operation succeeded
`400 Bad Request`	Invalid request	Unsupported actions for entity, malformed JSON
`401 Unauthorized`	Authentication failed	Missing or invalid API key/credentials
`404 Not Found`	Webhook not found	Invalid webhook ID
`500 Internal Server Error`	Server error	Contact support

Placeholders

Placeholders allow you to customize webhook URLs and payloads with dynamic values. When a webhook is triggered, placeholders are replaced with actual data from the event.

Mailchimp example

This guide demonstrates how to set up a webhook to send an email with mailchimp on various events an order can go through in Geins.