Publishing Webhook Events

overview the following guide provides step by step instructions for getting started with webhooks, covering the essentials of event publishers to learn about subscribing to webhook events, see our subscribing to webhook events guide app configuration developers can register their apps as publishers of events by creating an app configuration with the webhooks service this allows other apps to subscribe to events published by their apps as a publisher, you must specify a subscriber's permissions to receive your events these should match the permissions and resources defined in your app's aaa configuration for example, if your app has a get user details permission to access /api/v1/users/{userid} , you would include get user details in the createappconfig request you can provide a name that subscribers will see when they view available apps and events to subscribe to if not specified, your app's listing name from the developer portal will be used when subscribers attempt to subscribe to your app's events, the webhooks service will check if they have one of the roles and permissions you configured this allows you to control access to your app's events create app configuration publishers must call createappconfig to allow other apps to subscribe to their events refer to the events schema below to specify the attributes for creating an app configuration body parameters parameter description permissions list of permissions required to control an app's access rights name a user friendly name that subscribers will see for the app when getting available publishers and subscribing to events the following request list the get users , get user details , and update user and a user management name example request { "permissions" \[ "get users", "get user details", "update user" ], } example response { "data" { "id" "app 1234test 1aa1 1234 12aa 1234abcd5678" } } the response includes the data object with the appid events webhook events refer to specific occurrences or actions within a service that applications can keep track of these events may vary from changes in data, user actions, system alerts, or other important activities by registering webhook events, publishers can send event objects as part of a post request to the subscribers registered to webhook urls registering events publishers must register events must before an application subscribers can subscribe to them this process involves defining the event and specifying the conditions under which it is triggered once publisher service developers identify the events relevant to their application/consumer developer’s functionality, they can use the registerevents api to register identified events refer to the events schema below to specify the attributes of events path parameters parameter description topic the topic name possible values participant entity container body parameters parameter description events an array of event objects that describe the events for which notifications are to be sent events name a user friendly name of the event example availableuserevent events description description of the event api events eventtype the event name see egress events for publishers https //docs getos1 com/webhook egress events for available event types published by participant, entity, and container services example applyeventparticipantsuccessevent events filterlogic the json logic to define filters on additional attributes to further control which messages get sent to subscribers of that event example orderedmap { "===" list \[ orderedmap { "var" list \[ "event state" ] }, "active\ available" ] } events type the type of the event defined in the configuration example users the following example request registers the usercreated and userupdated events registerevents { "getapipath" "/app/api/v2/users/{userid}", "events" \[ { "name" "usercreated", "description" "when a new user is created", "eventtype" "usercreatedevent", "filterlogic" { "===" \[ "$eventtype", "usercreatedevent" ] }, "type" "users" }, { "name" "userupdated", "description" "when user data is updated", "eventtype" "userupdatedevent", "filterlogic" { "===" \[ "$eventtype", "userupdatedevent" ] }, "type" "users" } ] } get events use the getpublisherevents endpoint to retrieve all events by topic path parameters parameter description topic the topic name possible values participant entity container the following is an example response { "data" { "events" \[ { "name" "availableuserevent", "type" "users", "appid" "app\ dafee37d 7c50 4772 9725 8c8e2e598148", "description" "when the user state is changed to active this event will be sent " } ], "meta" { "nextpage" "string", "hasnextpage" true } } } update events use the updatepublisherevents endpoint to update the details of an event provide the following parameters below path parameters parameter description topic the topic name possible values participant entity container eventname name of the event body parameters parameter description events an array of eventdetails objects for which notifications will be sent must contain at least 1 item events name user friendly name of the event example availableuserevent events description description of the event api events appid the appid of the app which published this event events getapipath the api path through which the resource will be accessible example /app/api/v2/users/51941b1e c356 4563 a245 66438a19585e events eventtype the event name in the kafka message example applyeventparticipantsuccessevent events filterlogic the json logic to define filters on additional attributes to further control which messages get sent to subscribers of that event example orderedmap { "===" list \[ orderedmap { "var" list \[ "event state" ] }, "active\ available" ] } events type the type of the event defined in configuration example users bulk delete events use the bulkdeleteevents endpoint to delete publisher events in bulk refer to the table below for the parameters path parameters parameter description topic the topic name possible values participant entity container body parameters parameter description events the event names to be deleted a max of 25 events are allowed to be deleted in a request the following request deletes the availableuserevent and applyeventparticipantsuccessevent events { "events" \[ "availableuserevent", "applyeventparticipantsuccessevent" ] } remove events { "action" "remove", "events" \[ "orderpacked", "orderdispatched" ] }