Subscribing to Webhook Events

14min

Overview
The following guide provides step-by-step instructions for getting started with webhooks, covering the essentials of event subscription management. To learn about publishing webhook events, see our Publishing Webhook Events guide.
Subscribing to Events
Follow the steps below to start subscribing to webhook events in your app.
Step 1: Check for Existing Subscriptions 
Call GetSubscriptions or GetSubscriptionById to get a list of existing subscriptions for the app. See the following examples responses below:
getSubscriptions
getSubscriptionById
{
  "data": {
    "meta": {
      "nextPage": "string",
      "hasNextPage": true
    },
    "subscriptions": [
      {
        "id": "string",
        "description": "This is a sample subscription",
        "topic": "sample-topic-name",
        "eventAppId": "string",
        "isActive": true,
        "customAttr": true
      }
    ]
  },
  "error": {
    "code": "string",
    "description": "string",
    "additionalInfo": {
      "errorTrace": [
        {}
      ]
    }
  },
  "request": {
    "uri": "string",
    "method": "POST",
    "queryString": "string",
    "body": {}
  }
}
{
  "data": {
    "meta": {
      "nextPage": "string",
      "hasNextPage": true
    },
    "subscriptions": [
      {
        "id": "string",
        "description": "This is a sample subscription",
        "topic": "sample-topic-name",
        "eventAppId": "string",
        "isActive": true,
        "customAttr": true
      }
    ]
  },
  "error": {
    "code": "string",
    "description": "string",
    "additionalInfo": {
      "errorTrace": [
        {}
      ]
    }
  },
  "request": {
    "uri": "string",
    "method": "POST",
    "queryString": "string",
    "body": {}
  }
}
﻿
Step 2: Retrieve Published Events
Use the GetPublisherEvents endpoint to retrieve all events by topic. 
Path Parameters
Parameter
Description
topic
The topic name. Possible values:
participant
entity
container
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
    }
  }
}
﻿
Step 3: Create a Subscription
Call CreateSubscription to add your webhook notification URL and the events you wish to subscribe to. Refer to the table below for the CreateSubscription schema:
Body Parameters
Parameter
Description
description
The description of the subscription. 
Example: "Subscription for user state change events".
topic*﻿
The topic from which to receive events. 
Pattern: ^[a-zA-Z0-9\._\-]+$. Example: participant. 
Enum: [participant, entity, container].
events
List of events. A max of 20 events are allowed at a time in a subscription at creation.
isActive
Indicates whether this subscription configuration is active. Default: true.
customAttr
Indicates if the subscription includes custom attributes. 
Default: false.
webhook*﻿
Contains url and signatureKey.
webhook.url*﻿
The URL on which notifications will be sent. 
Example: https://example.com/webhook.
webhook.signatureKey*﻿
The HMAC authentication secret key in base64 encoded format. Example: base64encodedSignature.
The following example CreateSubscription request includes the following:
Creates a subscription for the OrderCreated and OrderStatusUpdated events published with the app:1f36d53c-fcc4-42d2-a753-33044f5c5f77 appId. 
The topic field specifies which Kafka topic the events will read from. 
When events occur, the app will send payloads to the specified webhook URL https://your-app.com/order-webhooks for handling. 
﻿
createSubscription
{
  "description": "Webhook subscription for order updates",
  "topic": "participant",
  "eventAppId": "app:1f36d53c-fcc4-42d2-a753-33044f5c5f77", 
  "events": [
    "ParticipantCreationSuccess", 
    "UpdateParticipantSuccess"
  ],
  "isActive": true, 
  "customAttr": false,
  "webhook": {
    "url": "https://your-app.com/order-webhooks", 
    "signatureKey": "your_base64_hmac_key"
  }  
}
{
  "description": "Webhook subscription for order updates",
  "topic": "participant",
  "eventAppId": "app:1f36d53c-fcc4-42d2-a753-33044f5c5f77", 
  "events": [
    "ParticipantCreationSuccess", 
    "UpdateParticipantSuccess"
  ],
  "isActive": true, 
  "customAttr": false,
  "webhook": {
    "url": "https://your-app.com/order-webhooks", 
    "signatureKey": "your_base64_hmac_key"
  }  
}
﻿
Here is a sample response for the createSubscription request:
createSubscription
{
    "data": {
        "id": "12345abcd-4321-1abc-2efg-f15212191784"
    }
}
{
    "data": {
        "id": "12345abcd-4321-1abc-2efg-f15212191784"
    }
}
﻿
﻿
Update Webhook Subscriptions
You can update existing webhook subscriptions by calling UpdateSubscriptions, which allows developers to modify the following subscription parameters:
Description
Events
Active status
Webhook URL
Signature key
Custom attributes
Refer to the table below for the UpdateSubscriptionsE schema:
Body Parameters
Parameter
Description
description
The description of the subscription. 
Example: "Subscription for user state change events".
topic
The topic from which to receive events. 
Pattern: ^[a-zA-Z0-9\._\-]+$. Example: participant. 
Enum: [participant, entity, container].
events
List of events. A max of 20 events are allowed at a time in a subscription at creation.
isActive
Indicates whether this subscription configuration is active. Default: true.
customAttr
Indicates if the subscription includes custom attributes. 
Default: false.
webhook
Contains url and signatureKey.
webhook.url
The URL on which notifications will be sent. 
Example: https://example.com/webhook.
webhook.signatureKey
The HMAC authentication secret key in base64 encoded format. Example: base64encodedSignature.
Here is a sample UpdateSubscription request:
updateSubscription
{
  "description": "This is a sample subscription",
  "events": [
    "OrderCreated",
    "OrderPacked"  
  ],
  "isActive": true,
  "customAttr": true,
  "webhook": {
    "url": "https://my-app.com/order-hooks",
    "signatureKey": "bXktbmV3LXNlY3JldC1rZXk="
  }
}
{
  "description": "This is a sample subscription",
  "events": [
    "OrderCreated",
    "OrderPacked"  
  ],
  "isActive": true,
  "customAttr": true,
  "webhook": {
    "url": "https://my-app.com/order-hooks",
    "signatureKey": "bXktbmV3LXNlY3JldC1rZXk="
  }
}
﻿
The example UpdateSubscription request updated the following:
description: Updated subscription description
events: Updated list of 2 events
isActive: Sets status to active
customAttr: Enables custom attributes
webhook.url: Updated webhook URL
webhook.signatureKey: New base64 encoded HMAC key
Add/Remove Subscription Events
To add or remove specific subscription events, call PatchSubscriptionsEvents. 
Refer to the table below for the updateSubscriptionEvents schema:
Body Parameters
Parameter
Data Type
Description
action
string
Specifies the action to be performed on the events. Options: add, remove.
events
array
A list of event names to be added or removed. Max 20 events can be handled in one API call. Example: ["event1", "event2"].
Here is a sample updateSubscriptionEvents request:
Add Events
{
  "action": "add",
  "events": [
    "UpdateParticipantSuccess",
    "UpdateParticipantFailed",
    "ApplyEventParticipantSuccess"  
  ] 
}
{
  "action": "add",
  "events": [
    "UpdateParticipantSuccess",
    "UpdateParticipantFailed",
    "ApplyEventParticipantSuccess"  
  ] 
}
﻿
The example would add 3 new events (OrderDispatched, OrderDelivered, and PaymentCaptured) events. 
To remove events, you would use the remove action instead. 
Remove Events
{
  "action": "remove",
  "events": [
    "ParticipantCreationSuccess",
    "ParticipantCreationFailed"
  ]
}
{
  "action": "remove",
  "events": [
    "ParticipantCreationSuccess",
    "ParticipantCreationFailed"
  ]
}
﻿
﻿

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

Parameter	Description
description	The description of the subscription. Example: "Subscription for user state change events".
topic*	The topic from which to receive events. Pattern: ^[a-zA-Z0-9\._\-]+$. Example: participant. Enum: [participant, entity, container].
events	List of events. A max of 20 events are allowed at a time in a subscription at creation.
isActive	Indicates whether this subscription configuration is active. Default: true.
customAttr	Indicates if the subscription includes custom attributes. Default: false.
webhook*	Contains url and signatureKey.
webhook.url*	The URL on which notifications will be sent. Example: https://example.com/webhook.
webhook.signatureKey*	The HMAC authentication secret key in base64 encoded format. Example: base64encodedSignature.

Parameter	Description
description	The description of the subscription. Example: "Subscription for user state change events".
topic	The topic from which to receive events. Pattern: ^[a-zA-Z0-9\._\-]+$. Example: participant. Enum: [participant, entity, container].
events	List of events. A max of 20 events are allowed at a time in a subscription at creation.
isActive	Indicates whether this subscription configuration is active. Default: true.
customAttr	Indicates if the subscription includes custom attributes. Default: false.
webhook	Contains url and signatureKey.
webhook.url	The URL on which notifications will be sent. Example: https://example.com/webhook.
webhook.signatureKey	The HMAC authentication secret key in base64 encoded format. Example: base64encodedSignature.

Parameter	Data Type	Description
action	string	Specifies the action to be performed on the events. Options: add, remove.
events	array	A list of event names to be added or removed. Max 20 events can be handled in one API call. Example: ["event1", "event2"].

Publishing Webhook Events

Egress Events for Publishers