{ "openapi": "3.0.1", "info": { "title": "Lockers Webhook APIs", "description": "The Webhook APIs enable event-driven communication by delivering real-time notifications when specific events occur. Webhook configurations define:\n- The event types to subscribe to\n- The target endpoint URL where notifications are delivered\n- The authorization details required for secure communication\n\nOnce configured, event notifications are triggered and pushed to the registered endpoint whenever the subscribed events occur.\n \n- Event notifications are delivered to the configured endpoint when subscribed events occur\n- Only events explicitly configured in the webhook are triggered\n- Each webhook configuration is uniquely identified by webHookConfigID\n- Updates to a webhook configuration immediately affect subsequent event notifications\n- Deleted webhook configurations stop receiving event notifications\n", "version": "0.1" }, "servers": [ { "url": "https://api-sandbox.sendpro360.pitneybowes.com/webhook", "description": "Sandbox Server for Webhook API's" }, { "url": "https://api.sendpro360.pitneybowes.com/webhook", "description": "Production Server for Webhook API's (uses live data)" } ], "tags": [ { "name": "Webhook", "description": "APIs for managing webhook configurations and event subscriptions. These APIs support operations such as retrieving supported events, creating webhook configurations, fetching webhook details, updating configurations, and deleting webhooks." } ], "paths": { "/api/v1/events": { "get": { "tags": [ "Webhook" ], "summary": "Get Applicable Event list for Webhook configuration", "description": "This operation gets the events details", "operationId": "getEvents", "responses": { "200": { "description": "Successfully retrieved all applicable events on which webhook can be configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/webhookConfig": { "post": { "tags": [ "Webhook" ], "summary": "Create Webhook configuration", "description": "Webhook provides the mechanism to push locker events as they occur. With help of this user would be able to receive events as they are generated and is received to the end user. This operation creates a webhook configuration. It needs details of events for which webhook tracking is required also the URL with its authorization details to which the locker events be pushed.", "operationId": "postWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Webhook" ], "summary": "Get All Webhooks", "description": "This operation gets all the configured webhook and its details.", "operationId": "getAllWebhook", "responses": { "200": { "description": "all Webhooks get successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponseAll" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/webhookConfig/{webHookConfigID}": { "put": { "tags": [ "Webhook" ], "summary": "Update Webhook", "description": "This operation updates the webhook details", "operationId": "putWebhook", "parameters": [ { "name": "webHookConfigID", "description": "This is unique id of webhook which will get from create webhook config api.", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook update is successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Webhook" ], "summary": "Get Webhook details by Id", "description": "This operation gets the webhook details", "operationId": "getWebhook", "parameters": [ { "name": "webHookConfigID", "description": "This is unique id of webhook which will get from create webhook config api.", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Webhook" ], "summary": "Delete Webhook", "description": "This operation delete the webhook", "operationId": "deleteWebhook", "parameters": [ { "name": "webHookConfigID", "description": "This is unique id of webhook which will get from create webhook config api.", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted successful" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "responses": { "UnauthorizedError": { "description": "The request could not be authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "CreateWebhookRequest": { "type": "object", "required": [ "type", "name", "events", "url", "authParams" ], "properties": { "name": { "type": "string", "description": "It indicates the desired name of the webhook
`Max length = 50`.", "example": "webhook1" }, "type": { "type": "string", "description": "It indicates the type of webhook. Currently it takes `tracking` and `locker`as value. These event codes are supported for the defined type: \n| type | supported events |\n|----------|----------------------------------------------------------------------------------|\n| locker | reservation, cancelreservation, deposit, pickup, stalemailpickup, onhold |\n| tracking | Manifest, Acceptance, InTransit, DeliveryAttempt, OutForDelivery, Delivered, Exception, ReturnToSender, ReadyForPickup, PickupMissed, PickedUp |\n", "enum": [ "locker", "tracking" ] }, "events": { "type": "array", "items": { "type": "string", "description": "Indicates the list of events for which notifications will be received.\n\n| type | supported events |\n|----------|----------------------------------------------------------------------------------|\n| locker | reservation, cancelreservation, deposit, pickup, stalemailpickup, onhold |\n| tracking | Manifest, Acceptance, InTransit, DeliveryAttempt, OutForDelivery, Delivered, \n Exception, ReturnToSender, ReadyForPickup, PickupMissed, PickedUp |\n" }, "example": [ "Manifest", "InTransit", "Delivered" ] }, "url": { "type": "string", "description": "It indicates the customer url to which events should be sent.", "example": "https://webhook.com" }, "timeOut": { "type": "number", "description": "It indicates the timeout value before system waits response from the customer url, here timeout indicates in seconds.", "example": 5 }, "status": { "type": "string", "description": "It indicates the status of the webhook. By default it takes `active`. To mark it inactive use `in-active`", "example": "active" }, "authParams": { "oneOf": [ { "$ref": "#/components/schemas/custom" }, { "$ref": "#/components/schemas/basic" }, { "$ref": "#/components/schemas/OAuth" } ] } }, "example": { "name": "dev_webhook1", "type": "locker", "events": [ "reservation", "cancelreservation", "deposit" ], "url": "https://webhook.com", "timeOut": 5, "status": "active", "authParams": { "authType": "custom", "apiKey": "JsuG7jk", "headerName": "webhook1" } } }, "custom": { "type": "object", "properties": { "authType": { "type": "string", "description": "It indicates the authoriation mechanism required to authenticate the customer url. here in this case authType is `custom`.", "example": "custom" }, "apiKey": { "type": "string", "description": "It indicates api key for authentication", "example": "JsuG7jk" }, "headerName": { "type": "string", "description": "It indicates header name for authentication", "example": "webhook1" } } }, "basic": { "type": "object", "properties": { "authType": { "type": "string", "description": "It indicates the authoriation mechanism required to authenticate the customer url. here in this case authType is `basic`.", "example": "basic" }, "clientID": { "type": "string", "description": "It indicates client id for authentication", "example": "JsuG7jk1fdjfh" }, "secret": { "type": "string", "description": "It indicates secret key for authentication", "example": "nejhdsugduwinduwbduhsidn" } } }, "OAuth": { "type": "object", "properties": { "authType": { "type": "string", "description": "It indicates the authoriation mechanism required to authenticate the customer url. here in this case authType is `basic`.", "example": "oauth" }, "clientID": { "type": "string", "description": "It indicates client id for authentication", "example": "JsuG7jk1fdjfh" }, "secret": { "type": "string", "description": "It indicates secret key for authentication", "example": "nejhdsugduwinduwbduhsidn" }, "tokenUrl": { "type": "string", "description": "The URL for retrieving a token.", "example": "https//webhook1" } } }, "WebhookResponse": { "type": "object", "properties": { "webHookConfigID": { "type": "string", "description": "It is unique id system generates for the created webhook", "example": "1Q86AvxyqmA" }, "name": { "type": "string", "description": "name of the webhook", "example": "webhook1" }, "type": { "type": "string", "description": "It indicates the type of webhook. Currently it takes `tracking` and `locker`as value. These event codes are supported for the defined type: \n| type | supported events |\n|----------|----------------------------------------------------------------------------------|\n| locker | reservation, cancelreservation, deposit, pickup, stalemailpickup |\n| tracking | Manifest, Acceptance, InTransit, DeliveryAttempt, OutForDelivery, Delivered, Exception, ReturnToSender, ReadyForPickup, PickupMissed, PickedUp |\n", "enum": [ "locker", "tracking" ] }, "events": { "type": "array", "items": { "type": "string", "description": "Indicates the list of events for which notifications will be received.\n\n| type | supported Events |\n|----------|----------------------------------------------------------------------------------|\n| locker | reservation, cancelreservation, deposit, pickup, stalemailpickup |\n| tracking | Manifest, Acceptance, InTransit, DeliveryAttempt, OutForDelivery, Delivered, \n Exception, ReturnToSender, ReadyForPickup, PickupMissed, PickedUp |\n" }, "example": [ "Manifest", "InTransit", "Delivered" ] }, "url": { "type": "string", "description": "URL to which events be pushed to", "example": "https://webhook.com" }, "timeOut": { "type": "number", "description": "It shows the timeout value untill which it waits to receive response from the customer url, here timeout indicates in seconds.", "example": 5 }, "status": { "type": "string", "description": "status of the webhook", "example": "active" }, "authParams": { "oneOf": [ { "$ref": "#/components/schemas/custom" }, { "$ref": "#/components/schemas/basic" }, { "$ref": "#/components/schemas/OAuth" } ] } }, "example": { "webHookConfigID": "DELn75Jx7r3p", "name": "dev_webhook1", "type": "locker", "events": [ "reservation", "cancelreservation", "deposit" ], "url": "https://webhook.com", "authParams": { "authType": "custom", "apiKey": "JsuG7jk", "headerName": "webhook1" }, "timeOut": 5, "status": "active", "developerPartnerId": "xxxxxx" } }, "WebhookResponseAll": { "type": "object", "properties": { "webHookConfigID": { "type": "string", "description": "webhook config id of the webhook", "example": "1Q86AvxyqmA" }, "name": { "type": "string", "description": "name of the webhook", "example": "webhook1" }, "type": { "type": "string", "description": "It indicates the type of webhook. Currently it takes `tracking` and `locker`as value. These event codes are supported for the defined type: \n| type | supported events |\n|----------|----------------------------------------------------------------------------------|\n| locker | reservation, cancelreservation, deposit, pickup, stalemailpickup |\n| tracking | Manifest, Acceptance, InTransit, DeliveryAttempt, OutForDelivery, Delivered, Exception, ReturnToSender, ReadyForPickup, PickupMissed, PickedUp |\n", "enum": [ "locker", "tracking" ] }, "events": { "type": "array", "items": { "type": "string", "description": "Indicates the list of events for which notifications will be received.\n\n| type | supported events |\n|----------|----------------------------------------------------------------------------------|\n| locker | reservation, cancelreservation, deposit, pickup, stalemailpickup |\n| tracking | Manifest, Acceptance, InTransit, DeliveryAttempt, OutForDelivery, Delivered, \n Exception, ReturnToSender, ReadyForPickup, PickupMissed, PickedUp |\n" }, "example": [ "Manifest", "InTransit", "Delivered" ] }, "url": { "type": "string", "description": "url of the webhook", "example": "https://webhook.com" }, "timeOut": { "type": "number", "description": "timeout seconds", "example": 5 }, "status": { "type": "string", "description": "status of the webhook", "example": "active" }, "authParams": { "type": "object", "properties": { "authType": { "type": "string", "description": "auth type of webhook authentication", "example": "custom" }, "apiKey": { "type": "string", "description": "api key for webhook authentication", "example": "jsfjafhjfk" }, "headerName": { "type": "string", "description": "header name if webhook has any header name", "example": "webhook1" } } } }, "example": { "data": [ { "webHookConfigID": "DELn75Jx7r3p", "name": "dev_webhook1", "type": "locker", "events": [ "reservation", "cancelreservation", "deposit" ], "url": "https://webhook.com", "authParams": { "authType": "custom", "apiKey": "JsuG7jk", "headerName": "webhook1" }, "timeOut": 5, "status": "active", "developerPartnerId": "xxxxx" }, { "webHookConfigID": "K3M01oqmEbe2", "name": "dev_webhook1", "type": "locker", "events": [ "reservation", "cancelreservation", "deposit" ], "url": "https://webhook.com", "authParams": { "authType": "custom", "apiKey": "JsuG7jk", "headerName": "webhook1" }, "timeOut": 5, "status": "active", "developerPartnerId": "xxxxx" } ], "pageInfo": { "total": 2, "pages": 1, "page": 1 } } }, "EventResponse": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string", "description": "event id of an event" }, "name": { "type": "string", "description": "name of an event" } } }, "example": [ { "eventId": "reservation", "name": "reservation" }, { "eventId": "cancelreservation", "name": "cancelreservation" }, { "eventId": "deposit", "name": "deposit" }, { "eventId": "pickup", "name": "pickup" }, { "eventId": "stalemailpickup", "name": "stalemailpickup" }, { "eventId": "updatereservation", "name": "updatereservation" }, { "eventId": "onhold", "name": "onhold" } ] }, "Error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message", "code" ] }, "Empty": { "title": "Empty Schema", "type": "object" } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }