Publishing Webhook Events

17min

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
JSON
{
  "permissions": [
    "get-users",
    "get-user-details",
    "update-user"
  ],
}
{
  "permissions": [
    "get-users",
    "get-user-details",
    "update-user"
  ],
}
﻿
Example Response
JSON
{
    "data": {
        "id": "app:1234test-1aa1-1234-12aa-1234abcd5678"
    }
}
{
    "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 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"
    }
  ]
}
{
  "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:
JSON
{
  "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
    }
  }
}
{
  "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.
JSON
{
  "events": [
    "AvailableUserEvent",
    "ApplyEventParticipantSuccessEvent"
  ]
}
{
  "events": [
    "AvailableUserEvent",
    "ApplyEventParticipantSuccessEvent"
  ]
}
﻿
﻿
Remove Events
{
  "action": "remove",
  "events": [
    "OrderPacked",
    "OrderDispatched"
  ]
}
{
  "action": "remove",
  "events": [
    "OrderPacked",
    "OrderDispatched"
  ]
}
﻿
﻿

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.

Parameter	Description
topic	The topic name. Possible values: participant entity container

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 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

Parameter	Description
topic	The topic name. Possible values: participant entity container

Parameter	Description
topic	The topic name. Possible values: participant entity container
eventName	Name of the event.

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.

Parameter	Description
topic	The topic name. Possible values: participant entity container

Parameter	Description
events	The event names to be deleted. A max of 25 events are allowed to be deleted in a request.

Updated 11 Sep 2024

Did this page help you?

Webhooks

Subscribing to Webhook Events