This feature provides the possibility to integrate other sysmtes with Streto using webhooks.
An operator can setup the required listeners (webhooks) in the Admin, configuring which events are going to be attended.
When those events occur, Streto will trigger the webhooks requesting the configurated URLs, and including relevant information according to each event.
¶ Feature Details
- CRUD operations for webhooks available for operators
- Capability to enable and disable webhooks
- Retry schedule for failed webhook calls
- Registry of webhook calls and retries
- Auto-disabling of constantly failed webhooks with operators notification
- Webhook test functionality for integrators
¶ Event Flows
These are the main flows that could occur when using webhooks.
¶ Happy Path
Case when an event raises the execution of a webhook that is successfully executed in the first try.
¶ Retry Flow
Case when an event raises the execution of a webhook that fails in the first execution and succeeds after a retry.
¶ Auto-Disabling
Case when under multiple successive failures the webhok is automatically disabled and the operators are notified.
¶ Data Model
¶ Webhook (Webhook)
Store and manage the integrations.
Fields
Identifier (id): [string, read only UUIDv4] The identifier of the entity.
Creation Date (createdAt): [Date, read only] The creation date-time of the entity.
Update Date (updatedAt): [Date, read only] The las update date-time of the entity. If empty means the entity was not modified since creation.
Name (name): [string] Name of the webhook to be identified by operators.
Description (description): [string] Description of the webhook to explain details about its purpose.
URL (url): [string] URL setup by the operator to hit the integration.
Events (eventCodes): [string[]] List of event codes to listen to. Check the possible event codes in the Events sub-section.
Enabled (enabled): [boolean, default false] Flag to enable or disable the webhook.
Successive Failures (successiveFailureCount): [number] Number of successive failures after a webhook instance is executed. When an execution is successful, this value is reset. It is also reset when a disabled webhook is enabled.
Operations
Create: [POST /webhooks] Creates a webhook.
Edit: :[PATCH /webhooks/{id}] Updates a webhook
Delete: [DELETE /webhooks/{id}] Deletes a webhook.
List: [GET /webhooks] Lists webhooks with filter and pagination support.
Count: [GET /webhooks/count] Counts webhooks with filter support.
Get by Id: [GET /webhooks/{id}] Returns a webhook by id.
Test Integration: [POST /webhooks/{id}/test] Executes the webhook with test data without affecting the API state in any way. For integration testing purposes.
List Events: [GET /webhook-events] Lists webhook events.
Count Events: [GET /webhook-events/count] Counts webhook events.
¶ Webhook Instance (WebhookInstance)
Represents an specific instance of a webhook created when an event was triggered.
Fields
Identifier (id): [string, read only UUIDv4] The identifier of the entity.
Webhook (webhookId): [string, read only]
Trigger Date (createdAt): [Date, read only] The creation date-time of the entity.
Update Date (updatedAt): [Date, read only] The las update date-time of the entity. If empty means the entity was not modified since creation.
State (state): [on of "new", "running", "success", "failed", "canceled"] State of the webhook instance. See state details below.
Remaining Retries (remainingRetries): [number, integer >= 0] Number of pending retries to be performed in case of failure. If it is 0 means no retries are pending.
Event (eventCode): [string] Event code of the webhook instante. Check the possible event codes in the Events sub-section.
Event Data (payload): [object] Data related to the event that is included in the webhook requests' body. Check the events details in the Events sub-section.
Execution History (executions): [WebhookExec[]] List of executions of the webhook instance.
State details:
| State | Description |
|---|---|
"new" |
The instance has not been executed yet. |
"running" |
The instance is being executed. |
"success" |
The instance was executed successfully. |
"failed" |
The last try of executing the instance failed. Depending on the value of remainingRetries the instance could or could not have more retries of execution. |
"canceled" |
The instance failed to execute and retries has been canceled by the operator. |
Operations
List by Webhook: [GET /webhooks/{id}/instances] List instances of a webhook with filter and pagination support.
Count by Webhook: [GET /webhooks/{id}/instances/count] Count instances of a webhook with filter support.
Get by Id: [GET /webhook-instances/{id}] Returns a webhook instances by id.
Execute Now: [POST /webhook-instances/{id}/execute] Executes a new try of the instance without waiting for the retry schedule after been failed in the previous try.
Cancel: [POST /webhook-instances/{id}/cancel] Cancel the retries schedule of the webhook instance that previously failed.
¶ Webhook Execution (WebhookExec)
Represents each try of an execution of a webhook instance. An instance could have one or more executions, until one of them finishes successfully or the number of remaining retries is zero.
Fields
Identifier (id): [string, read only UUIDv4] The identifier of the entity.
Execution Date (createdAt): [Date, read only] The date-time of the execution.
Success (success): [boolean] Result of the webhook execution.
Message (message): [string] Message describing the execution result.
Response Status Code (responseStatus): [number | undefined] HTTP status code of the response, or undefined if request could not be performed.
Response Headers (responseHeaders): [object] Map of response headers or undefined (field not present) when the request could not be performed.
Response Body (responseBody): [string | object | null | undefined] Response of the webhook execution, if any. The value will be an object if the response has a valid JSON and the content type is application/json. The value will be a string if a non-JSON is returned. The value will be null if the response has no body. The value will be undefined (field not present) when the request could not be performed.
Operations
None
¶ Webhook Body (WebhookBody)
Represents the data sent to the integrator's webhook.
Fields
Identifier (id): [string, read only UUIDv4] The identifier of the webhook execution.
Webhook (webhookId): [string, read only UUIDv4] The identifier of the webhook.
Event (eventCode): [string] Event code of the webhook instante. Check the possible event codes in the Events sub-section.
Retry Number (retryNumber): [number, integer >= 0] Retry number of the webhook instance. If it is 0 means it is the first try.
Event Data (payload): [object] Data related to the event that is included in the webhook requests' body. Check the events details in the Events sub-section.
Operations
None
¶ Events
This section describes the specific supported events, its model and related definitions.
¶ Event Model
The event model is described in the Data Model section as Webhook Body.
{
"id": "9a91b41b-d52c-4c3b-844f-c6d8af3046a1",
"webhookId": "141b8bb3-2b86-4278-80c6-c8d4c21ce371",
"eventCode": "import.started",
"retryNumber": 2,
"payload": {
// The payload is a variable object that depends on the event
}
}
For detailed information about the content of this field, check the payload examples on each individual event in List of Events sub-section.
¶ List of Event
The available events that can be used to execute webhooks are:
¶ Imports
Import Started ("import.started"): When an import process starts.
Payload example
{
"id": "d88ab663-96d8-493a-b7a4-0832e1bbeb6d",
"createdAt": "2011-10-05T14:48:00.000Z",
"operatorId": "4b32dade-da90-4f53-a66f-b776fab25a81",
"status": "new",
"entity": "product",
"source": "csv",
"entityCount": 1502,
"processedOk": 0,
"processedFails": 0,
"additionalInformation": {}
}
Import Finished ("import.finished"): When an import process finishes successfully or not.
Payload example
{
"id": "d88ab663-96d8-493a-b7a4-0832e1bbeb6d",
"createdAt": "2011-10-05T14:48:00.000Z",
"updatedAt": "2011-10-05T15:01:20.000Z",
"operatorId": "4b32dade-da90-4f53-a66f-b776fab25a81",
"status": "finished",
"entity": "product",
"source": "csv",
"entityCount": 1502,
"processedOk": 1500,
"processedFails": 2,
"additionalInformation": {}
}
¶ Orders
Order Created ("order.created"): When an order is created.
Payload example
{
"id":"6f1f6af7-d8bb-4e35-98f3-b80c1cd8a42d",
"createdAt":"2023-11-09T17:23:20.707Z",
"cartId":"6acc0f70-5d7c-4e31-b8a6-5fcb2f267e4a",
"owner":"03320828-c63a-43ca-84ed-bc30b0054457",
"creator":{
"userType":"customer",
"userId":"03320828-c63a-43ca-84ed-bc30b0054457"
},
"state":"pending",
"orderNumber":"0000000001",
"currencyCode":"ARS",
"items":[
{
"id":"ec24e065-f53d-4f05-b749-2c1d83736b32",
"productId":"b96e451a-fb88-4330-9c47-299e015cf376",
"finalProductId":"b96e451a-fb88-4330-9c47-299e015cf376",
"qtyOrdered":1,
"qtyInvoiced":0,
"qtyShipped":0,
"shippable":true,
"taxes":[],
"details":{
"name":"simple",
"sku":"simple"
},
"totals":{
"unit":10,
"unitDiscount":0,
"subtotal":10,
"discount":0,
"tax":0,
"grandTotal":10
}
}
],
"shippingAddresses":[
{
"id":"7b295b60-e89e-49b7-ae20-b4a222029797",
"personalInfo":{
"firstName":"Daniel",
"lastName":"Duarte"
},
"countryCode":"AR",
"regionCode":"AR-B",
"city":"Buenos Aires",
"postalCode":"7890",
"street":"Fake St. 1234\n",
"phone":"4845219794",
"shippingMethods":[
{
"id":"8e568898-51f8-4b8c-9a4f-a4a44fc28fe5",
"carrierCode":"streto",
"methodCode":"offline",
"totals": { "shipping":0 },
"items":[
{
"itemId":"ec24e065-f53d-4f05-b749-2c1d83736b32",
"qty":1
}
],
"additionalInformation":{
"title":"Offline"
}
}
],
"totals":{
"shipping":0
}
}
],
"billingAddresses":[
{
"id":"13eebd80-019a-40f8-b61a-d39ff609cff0",
"personalInfo":{
"firstName":"Daniel",
"lastName":"Duarte"
},
"countryCode":"AR",
"regionCode":"AR-B",
"city":"Buenos Aires",
"postalCode":"7890",
"street":"Fake St. 1234\n",
"phone":"4845219794",
"notes":""
}
],
"paymentMethods":[
{
"id":"46c70b13-8d53-4725-9d4e-c93bdb947bfa",
"code":"mobbex",
"additionalInformation":{
"title":"Mobbex"
}
}
],
"coupons":[],
"history":[
{
"id":"f8cf65a6-555c-4d3d-950e-b69e61530f22",
"createdAt":"2023-11-09T17:23:20.663Z",
"title":"Order created",
"stateFrom":null,
"stateTo":"pending"
}
],
"totals":{
"globalTax":0,
"subtotal":10,
"shipping":0,
"tax":0,
"promotionsDiscount":0,
"couponsDiscount":0,
"globalDiscount":0,
"discount":0,
"grandTotal":10
}
}
Order Updated ("order.updated"): When an order has had a relevant update (some updates doesn't trigger this event).
Payload example
{
"id":"6f1f6af7-d8bb-4e35-98f3-b80c1cd8a42d",
"createdAt":"2023-11-09T17:23:20.707Z",
"updatedAt": "2024-01-15T16:40:36.829Z",
"cartId":"6acc0f70-5d7c-4e31-b8a6-5fcb2f267e4a",
"owner":"03320828-c63a-43ca-84ed-bc30b0054457",
"creator":{
"userType":"customer",
"userId":"03320828-c63a-43ca-84ed-bc30b0054457"
},
"state":"canceled",
"orderNumber":"0000000001",
"currencyCode":"ARS",
"items":[
{
"id":"ec24e065-f53d-4f05-b749-2c1d83736b32",
"productId":"b96e451a-fb88-4330-9c47-299e015cf376",
"finalProductId":"b96e451a-fb88-4330-9c47-299e015cf376",
"qtyOrdered":1,
"qtyInvoiced":0,
"qtyShipped":0,
"shippable":true,
"taxes":[],
"details":{
"name":"simple",
"sku":"simple"
},
"totals":{
"unit":10,
"unitDiscount":0,
"subtotal":10,
"discount":0,
"tax":0,
"grandTotal":10
}
}
],
"shippingAddresses":[
{
"id":"7b295b60-e89e-49b7-ae20-b4a222029797",
"personalInfo":{
"firstName":"Daniel",
"lastName":"Duarte"
},
"countryCode":"AR",
"regionCode":"AR-B",
"city":"Buenos Aires",
"postalCode":"7890",
"street":"Fake St. 1234\n",
"phone":"4845219794",
"shippingMethods":[
{
"id":"8e568898-51f8-4b8c-9a4f-a4a44fc28fe5",
"carrierCode":"streto",
"methodCode":"offline",
"totals": { "shipping":0 },
"items":[
{
"itemId":"ec24e065-f53d-4f05-b749-2c1d83736b32",
"qty":1
}
],
"additionalInformation":{
"title":"Offline"
}
}
],
"totals":{
"shipping":0
}
}
],
"billingAddresses":[
{
"id":"13eebd80-019a-40f8-b61a-d39ff609cff0",
"personalInfo":{
"firstName":"Daniel",
"lastName":"Duarte"
},
"countryCode":"AR",
"regionCode":"AR-B",
"city":"Buenos Aires",
"postalCode":"7890",
"street":"Fake St. 1234\n",
"phone":"4845219794",
"notes":""
}
],
"paymentMethods":[
{
"id":"46c70b13-8d53-4725-9d4e-c93bdb947bfa",
"code":"mobbex",
"additionalInformation":{
"title":"Mobbex"
}
}
],
"coupons":[],
"history":[
{
"id":"f8cf65a6-555c-4d3d-950e-b69e61530f22",
"createdAt":"2023-11-09T17:23:20.663Z",
"title":"Order created",
"stateFrom":null,
"stateTo":"pending"
},
{
"id":"6e21bc7e-1edd-456f-a502-9d17d449d7c0",
"createdAt":"2024-01-15T14:06:25.932Z",
"title":"Pago rechazado",
"stateFrom":"pending",
"stateTo":"canceled",
"details": {
"user": {
"type": "operator",
"id": "d259bdf5-d386-4477-bafb-a0582c0fd55c",
"name": "Dani Du"
}
}
}
],
"totals":{
"globalTax":0,
"subtotal":10,
"shipping":0,
"tax":0,
"promotionsDiscount":0,
"couponsDiscount":0,
"globalDiscount":0,
"discount":0,
"grandTotal":10
}
}
Shipment Created ("shipment.created"): When a shipping is created.
Payload example
{
"id":"3c990b9e-9707-4910-868e-07c85f23f670",
"createdAt": "2024-01-23T18:50:59.356Z",
"orderId":"fdb5edad-a8c8-4c24-b512-6eabeb66de29",
"state":"pending",
"number":"S000000000030",
"extra":{
"strategyCode":"andreani",
"methodCode":"option_2",
"senderFullName":"Main",
"recipientFullName":"Pedro Mancione",
"originAddress":{
"countryCode":"AR",
"regionCode":"AR-B",
"city":"Mar del Plata",
"postalCode":"7600",
"street":"Luro 1230",
"number":"500"
},
"shippingAddress":{
"countryCode":"AR",
"regionCode":"AR-H",
"city":"Tandil",
"postalCode":"7000",
"street":"Alberdi 350",
"number":"78"
},
"order":{}
},
"strategyCode":"andreani",
"methodCode":"option_4"
}
Shipment Updated ("shipment.updated"): When a shipping has had a relevant update (some updates doesn't trigger this event).
Payload example
{
"id":"3c990b9e-9707-4910-868e-07c85f23f670",
"createdAt": "2024-01-23T18:50:59.356Z",
"updatedAt": "2024-02-02T17:40:54.468Z",
"orderId":"fdb5edad-a8c8-4c24-b512-6eabeb66de29",
"state":"canceled",
"number":"S000000000030",
"extra":{
"strategyCode":"andreani",
"methodCode":"option_2",
"senderFullName":"Main",
"recipientFullName":"Pedro Mancione",
"originAddress":{
"countryCode":"AR",
"regionCode":"AR-B",
"city":"Mar del Plata",
"postalCode":"7600",
"street":"Luro 1230",
"number":"500"
},
"shippingAddress":{
"countryCode":"AR",
"regionCode":"AR-H",
"city":"Tandil",
"postalCode":"7000",
"street":"Alberdi 350",
"number":"78"
},
"order":{},
"update":{}
},
"strategyCode":"andreani",
"methodCode":"option_4"
}
Invoice Created ("invoice.created"): When an invoice is created.
Payload example
{
"id": "0d18374e-d515-4ac1-87f9-3fcd99aa7cdc",
"createdAt": "2024-02-21T14:10:34.411Z",
"orderId": "f1808856-c7bf-44f6-a1ec-7b17a03e142a",
"number": "I000000000003"
}
¶ Products
Product Created ("product.created"): When a product is created.
Payload example
{
"id": "6b8b4fd5-0855-4c98-aef9-4de53f3ae5b5",
"createdAt": "2024-03-06T18:57:33.762Z",
"type": "simple",
"attributes": {
"name": "X1-2",
"sku": "X1",
"enabled": true
},
"scopedAttributes": {},
"attributeSets": ["f95ef996-f263-4ed9-8d1f-f4c70ca18102"]
}
Product Updated ("product.updated"): When a product is updated.
Payload example
{
"id": "6b8b4fd5-0855-4c98-aef9-4de53f3ae5b5",
"createdAt": "2024-03-06T18:57:33.762Z",
"type": "simple",
"attributes": {
"name": "X1-2",
"sku": "X1",
"enabled": true
},
"scopedAttributes": {},
"attributeSets": ["f95ef996-f263-4ed9-8d1f-f4c70ca18102"],
"updatedAt": "2024-03-22T17:33:18.299Z"
}
¶ UI (Admin)
Screens description for the operator's UI of the feature.
¶ Webhook Grid
The main grid to manage webhook integrations.
¶ Webhook Form
Form to create and edit and test webhook and instances.
¶ Webhook Instance Details
Detailed view of Instances and their executions.
¶ Task Breakdown
Tasks
-
General:
-
API
-
General
-
Entity management
-
Event system
- Implement Webhook engine
- Implement events: Import Process
- Implement events: Order
- Implement events: Shipment
- Implement events: Invoice
- Implement events: Product
- Implement ruw now feature (include specs)
- Implement cancel feature (include specs)
- Implement retry schedule feature
Schedule:- Retry 1: 5' after first try
- Retry 2: 15' after first try (10' after last retry)
- Retry 3: 2h after first try (1h 45' after last retry)
- Retry 4: 12h after first try (10h after last retry)
- Implement auto-disabling feature
-
-
Admin:
-
Main grid
- Create grid of Webhooks accessible through sidebar
Columns:- Name (
name) - Created At (
createdAt) - Events (
eventCodes): Show titles, store codes - Recent Failures (
successiveFailureCount) - Enabled (
enabled) - Actions:
- Edit: Open edit form
- Delete: Delete with confirmation dialog
- Name (
- Create grid of Webhooks accessible through sidebar
-
Detail view
- Create new/edit form for Webhooks
Fields:- Name (
name) - Description (
description) - URL (
url) - Events (
eventCodes): Multi-select, show titles, store codes - Enabled (
enabled)
- Name (
- Create webhook instances grid
Columns:- Event (
eventCode): Show title, store code - Triggered At (
createdAt) - State (
state): Show with tag format - Remaining Retries (
remainingRetries) - Actions:
- View: Open Instance details.
- Run Now: Retries the instance execution without waiting for the schedule. Include confirmation dialog.
- Cancel: Cancels the instance to avoid retries. Include confirmation dialog.
- Event (
- Create Webhook instance details view
Fields:- Webhook (
webhookId): Show name - Event (
eventCode): Show title - Triggered At (
createdAt) - State (
state): Show with tag format - Remaining Retries (
remainingRetries) - Event Data (
payload): Show as read-only JSON editor
- Webhook (
- Create instance execution grid
Columns:- Executed At (
createdAt) - Success (
success) - Message (
message) - Status Code (
responseStatus)
- Executed At (
- Show Webhook execution details
Add the "Actions" column to execution grid, with the action "View Details"
This action opens popup showingresponseBodyin read only mode for all cases with these alternatives:- If field is an object: Show a JSON editor.
- If field is a string: Show a multi-line text editor.
- If field is null: Show the message "The integration endpoint did not return any body"
- If field is undefined (field not present): Show the message "The execution of the request could not be performed"
- Create new/edit form for Webhooks
-
Test view
-