openapi: 3.0.3 info: title: flexEngage Webhooks API description: > Webhooks provide a mechanism for you to be notified of events in our systems. You can learn more about the type of event notifications we publish as well as general development guidelines in our [webhook integration guide](./webhooks/webhooks-integration-guide.html).

__NOTE:__ Notifications are not enabled by default. Please work with your [support team](mailto:support@flexengage.com) to enable notifications for the events you are interested in. contact: name: FlexEngage Support email: support@flexengage.com version: 0.0.1 security: - bearerAuth: - flexengage.gateway/order.events.create servers: - url: 'https://api.flexengage-test.com' description: Test Environment - url: 'https://api.flexengage.com' description: Production Environment paths: /v1/{brandId}/webhooks: parameters: - name: brandId in: path required: true description: > This is your account identifier; we will provide this to you during the onboarding process. Please reach out to your flexEngage Customer Support Contact (support@flexengage.com) if you have not received one. schema: type: string post: tags: - Webhooks summary: Create a New Webhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequest' description: > This endpoint is used to create a new Webhook. Webhooks are enabled by default once they are created, but can be disabled using the PATCH API. A Webhook is essentially a HTTPS endpoint + a list of event types that you'd like to receive for that endpoint. Event types are organized in a heirarchical manner which allows you to subscribe to groups of event types without having to list each one out individually when you create the Webhook. Please see our [Webhooks Integration Guide](./webhooks/webhooks-integration-guide.html) for a deeper explanation of event types. responses: '201': description: The webhook was successfully created headers: Location: schema: type: string format: uri example: 'Location: https://api.flexengage.com/v1/mybrand/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6' content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '409': description: > A Webhook already exists for the same endpoint with the same event types. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: CONFLICT description: 'A webhook for endpoint: http://example.com and eventTypes: ["ORDER_EVENTS.OMS.ORDER_CREATED"] already exists' status: 409 '422': description: There is an error in the request. See the response body for more details. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: UNPROCESSABLE ENTITY description: There are errors in the request status: 422 validations: endpoint: endpoint is required '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 get: tags: - Webhooks summary: Get Webhooks description: Returns all webhooks for a Brand ID responses: '200': description: > A list of webhooks, if any, affiliated with the Brand ID. content: application/json: schema: type: array items: $ref: '#/components/schemas/WebhookResponse' '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '404': description: 'No brand or webhooks were found' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: NOT FOUND description: No webhooks with that brand ID were found status: 404 '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 /v1/{brandId}/webhooks/{id}: parameters: - name: brandId in: path required: true description: > This is your account identifier; we will provide this to you during the onboarding process. Please reach out to your flexEngage Customer Support Contact (support@flexengage.com) if you have not received one. schema: type: string - name: id in: path required: true description: The webhook ID schema: type: string format: uuid get: tags: - Webhooks summary: Get a webhook by ID description: Returns a Webhook with the corresponding ID if it exists responses: '200': description: > An object representing the webhook with corresponding ID content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '404': description: 'The brand or webhook could not be found' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: NOT FOUND description: 'A webhook with ID: 123 for brandId: ABC was not found' status: 404 '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 patch: tags: - Webhooks summary: Toggle a Webhook On or Off description: > This request allows you to turn a Webhook off without deleting it, or turn it back on if it was turned off. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookPatchRequest' responses: '204': description: > An object representing the Webhook that was successfully modified. content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '404': description: 'No brand or webhook was found' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: NOT FOUND description: No webhook with that brand ID was found status: 404 '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 delete: tags: - Webhooks summary: Delete a Webhook description: Completely deletes a Webhook if it exists. responses: '204': description: The webhook was deleted successfully '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '404': description: 'No brand or webhook was found' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: NOT FOUND description: No webhooks with that brand ID were found status: 404 '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 /v1/{brandId}/webhooks/{id}/events: parameters: - name: brandId in: path required: true description: > This is your account identifier; we will provide this to you during the onboarding process. Please reach out to your flexEngage Customer Support Contact (support@flexengage.com) if you have not received one. schema: type: string - name: id in: path required: true description: The webhook ID schema: type: string format: uuid - name: size in: query required: false description: The page size schema: type: integer default: 20 - name: start in: query required: false description: The query start time schema: type: string format: 'date-time' - name: end in: query required: false description: The query end time schema: type: string format: 'date-time' - name: startId in: query required: false description: The event ID used to start the page schema: type: string format: uuid get: tags: - Webhooks summary: Get the Events of a Webhook description: > This API allows you to fetch a paginated list of events that have been sent to a Webhook endpoint. When the response contains multiple pages, the next page of results can be accessed by passing the attribute `page.lastId` as the query parameter `startId`. responses: '200': description: The events were returned successfully content: application/json: schema: $ref: '#/components/schemas/WebhookEventsResponsePage' '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '404': description: 'No brand or webhook was found' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: NOT FOUND description: No webhook with that brand ID was found status: 404 '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 /v1/{brandId}/webhooks/{id}/events/{eventId}: parameters: - name: brandId in: path required: true description: > This is your account identifier; we will provide this to you during the onboarding process. Please reach out to your flexEngage Customer Support Contact (support@flexengage.com) if you have not received one. schema: type: string - name: id in: path required: true description: The webhook ID schema: type: string format: uuid - name: eventId in: path required: true description: The event ID schema: type: string format: uuid get: tags: - Webhooks summary: Get a webhook event by ID description: > This request returns a specific webhook event. Each event will contain a list of attempts which in turn contain the response returned by the respective webhook's endpoint (if there was one). responses: '200': description: The event was returned successfully content: application/json: schema: $ref: '#/components/schemas/WebhookEventResponse' '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '404': description: 'The brand, webhook, or event was not found' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: NOT FOUND description: No event with that ID was found status: 404 '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 /v1/{brandId}/webhooks/{id}/events/{eventId}/retry: parameters: - name: brandId in: path required: true description: > This is your account identifier; we will provide this to you during the onboarding process. Please reach out to your flexEngage Customer Support Contact (support@flexengage.com) if you have not received one. schema: type: string - name: id in: path required: true description: The webhook ID schema: type: string format: uuid - name: eventId in: path required: true description: The event ID schema: type: string format: uuid post: tags: - Webhooks summary: Asynchronously Retry a Webhook Event description: > This request will queue a Webhook event to be resent to an endpoint. Each retry will count as a new attempt. responses: '202': description: The retry request was accepted successfully. '401': description: > Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: > The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. '404': description: 'The brand, webhook, or event was not found' content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: NOT FOUND description: No event with that ID was found status: 404 '429': description: > The user has sent too many requests in a given amount of time ("rate limiting"). If you are rate-limited in any way you will receive a 429 status code, at which point your client application should respond with exponential backoff or a similar throttling measure. In general our limits are high enough that non-abusive request patterns will not trigger them. '500': description: > A server encountered an unexpected condition that prevented it from fulfilling the request please retry again your request. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' example: message: Internal Server Error description: The server encountered an unexpected error. status: 500 components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: APIErrorResponse: type: object title: API Error response description: > This object represents errors found during the handling of the request. properties: message: type: string description: The error message description: type: string description: A more detailed description of the error status: type: number description: This code matches the HTTP status code. validations: type: object description: > If the error is based on validation constraints, those constraints will be expressed in this map. WebhookRequest: type: object properties: endpoint: type: string format: uri example: https://example.com/my/webhook/endpoint events: type: array items: allOf: - $ref: '#/components/schemas/Events' enabled: type: boolean default: true required: - endpoint - events WebhookPatchRequest: type: object properties: enabled: type: boolean required: - enabled WebhookResponse: type: object properties: id: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 created: type: string format: 'date-time' updated: type: string format: 'date-time' endpoint: type: string format: uri example: https://example.com/my/webhook/endpoint events: type: array items: $ref: '#/components/schemas/Events' enabled: type: boolean WebhookEventResponse: type: object properties: id: type: string format: uuid type: $ref: '#/components/schemas/Events' created: type: string format: 'date-time' updated: type: string format: 'date-time' status: $ref: '#/components/schemas/EventStatus' attempts: type: array items: $ref: '#/components/schemas/WebhookEventAttempt' WebhookEventPageResponse: type: object properties: id: type: string format: uuid type: $ref: '#/components/schemas/Events' created: type: string format: 'date-time' updated: type: string format: 'date-time' status: $ref: '#/components/schemas/EventStatus' WebhookEventAttempt: type: object properties: id: type: string format: uuid created: type: string format: 'date-time' status: $ref: '#/components/schemas/EventStatus' request: $ref: '#/components/schemas/Request' response: $ref: '#/components/schemas/Response' WebhookEventsResponsePage: type: object properties: events: type: array items: $ref: '#/components/schemas/WebhookEventPageResponse' page: $ref: '#/components/schemas/Page' Events: type: string enum: - NOTIFICATION.SMS.RECEIPT - ORDER_EVENTS.OMS.ORDER_CONFIRMED - ORDER_EVENTS.OMS.ORDER_SHIPPED - ORDER_EVENTS.OMS.ORDER_CANCELLED - ORDER_EVENTS.OMS.ORDER_FTC_DELAYED - ORDER_EVENTS.OMS.ORDER_RETURN_RECEIVED - ORDER_EVENTS.OMS.ORDER_RETURN_REQUESTED - ORDER_EVENTS.OMS.ORDER_BACK_ORDERED - ORDER_EVENTS.OMS.ORDER_COMPLETED - ORDER_EVENTS.OMS.ORDER_CREDIT_ISSUED - ORDER_EVENTS.OMS.ORDER_PICKUP_READY - ORDER_EVENTS.OMS.ORDER_PICKUP_COMPLETED - ORDER_EVENTS.OMS.ORDER_PICKUP_REMINDED - ORDER_EVENTS.OMS.ORDER_PICKUP_SHOPPER_ARRIVED - ORDER_EVENTS.OMS.ORDER_PICKUP_SHOPPER_CONFIRMED - ORDER_EVENTS.OMS.ORDER_PICKUP_SHOPPER_IN_TRANSIT - ORDER_EVENTS.OMS.ORDER_PICKUP_DELAYED - ORDER_EVENTS.OMS.ORDER_SHIPMENT_UPDATED - ORDER_EVENTS.OMS.UNKNOWN - ORDER_EVENTS.TRACKING.SHIPMENT_PRE_TRANSIT - ORDER_EVENTS.TRACKING.SHIPMENT_IN_TRANSIT - ORDER_EVENTS.TRACKING.SHIPMENT_OUT_FOR_DELIVERY - ORDER_EVENTS.TRACKING.SHIPMENT_DELIVERED - ORDER_EVENTS.TRACKING.SHIPMENT_AVAILABLE_FOR_PICKUP - ORDER_EVENTS.TRACKING.SHIPMENT_RETURNED_TO_SENDER - ORDER_EVENTS.TRACKING.SHIPMENT_FAILURE - ORDER_EVENTS.TRACKING.UNKNOWN - RECEIPTS Page: type: object properties: size: type: integer default: 20 startId: type: string format: uuid nullable: true lastId: type: string format: uuid nullable: true EventStatus: type: string enum: - SUCCESS - FAILURE Request: type: object properties: endpoint: type: string format: endpoint example: https://example.com/my/webhook/endpoint headers: type: object example: User-Agent: FlexEngage Webhook Content-Type: application/json Response: type: object properties: statusCode: type: integer example: 200 headers: type: object example: Content-Type: application/json body: type: string example: '{"example": "response json"}' time: type: integer description: The response time in milliseconds example: 231