Webhook

Warning

🚧 BETA Feature This feature is in BETA and is subject to change.

Currently, there is no front-end available yet to manage webhooks—everything must be done via the API.

Prerequisites

• An access token for the HIPE instance

Create a webhook

To create a webhook, make a POST request to the /api/webhooks endpoint. See the API reference for more details.

Will need to provide:

Parameter	Type	Description
name	string	A descriptive name for your webhook
url	string	The endpoint URL that will receive the webhook events
events	string[]	Array of event patterns to subscribe to (e.g., ["event.**"] for all events). See Events Reference for the full list
authenticationType	string	Authentication method for the webhook endpoint: none, basic (http auth), or header
credentials	object	Authentication credentials based on the chosen type (e.g., {"name": "XXX", "token": "XXX"})
httpMethod	string	HTTP method for webhook requests: get, post, patch, put, or delete

curl --location 'https://{ YOUR INSTANCE }-hipe.packitoo.com/api/webhooks' \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "name": "My webhook",
    "url": "https://example.com/webhook",
    "events": ["event.**"],
    "authenticationType": "header",
    "credentials": {
        "name": "X-ACCESS-TOKEN",
        "token": "YOUR KEY"
    },
    "httpMethod": "post"
}

Example payload

Complete event schema could be found in API reference for more details.

interface WebhookPayload {
  eventName: string;
  event: {
    // Primary fields
    id: string; // unique
    code: number; // incremental
    createdAt: Date;
    version: string;
    type: EventType; // {CREATE, UPDATE, DELETE}
    category: string; // event name without prefix
    entity: EntityType | string; // entity type concerned (extended list)
    relation?: EntityType; // relation entity type concerned

    // Related entity ids (ressources)
    entityId?: string; // id of the entity (uuid)
    relationId?: string; // id of the relation entity when applicable (uuid)

    // Details
    fieldName?: string; // name of the specific entity property concerned (not always given)
    updatedColumns?: string[]; // names for the properties updated (not always given)
    updatedRelations?: string[]; // names for the relations updated (not always given)
    process?: string; // related to brief when applicable
  };
}

With each webhook event, you’ll receive:

• The type of entity and relation that changed (complete list there)
• The IDs needed to retrieve the updated data (id, entityId, relationId)

You can use this information to:

• Fetch up to date event resources
• Trigger specific business logic or workflows
• Run custom scenarios based on the changes

Pull event resources

You can use the entityId and relationId from the webhook payload to fetch the updated data.

curl --location 'https://{ YOUR INSTANCE }-hipe.packitoo.com/api/events/ressources/{EVENT ID}' \
--header 'X-ACCESS-TOKEN: { YOUR ACCESS TOKEN }'

for example:

You received a corrugated material compositions update event, you can use the ID from the webhook payload and fetch the updated entity directly from the API without the need to query the corrugated material compositions endpoint.

{
  "eventName": string, // example: "event.corrugated_material_compositions.updated"
  "event": {
    "id": uuid,
    "version": string,
    "type": EventType, // {CREATE, UPDATE, DELETE} in that case "UPDATE"
    "category": string, // example: "corrugated_material_compositions.updated"
    "entity": string, // example: "CORRUGATED_MATERIAL_COMPOSITIONS"
    "tableName": string, // example: "corrugated_material_compositions"
    "entityId": uuid,
    "updatedColumns": string[], // example: ["gsm"]
    "updatedRelations": string[], // example: ["supplier", "material"]
  },
  "entity": {
    "id": uuid,
    "reference": string | null,
    "composition": string,
    "enabled": boolean,
    "gsm": int,
    "supplierId": uuid,
    "materialId": uuid
  },
}