Subscribing to Webhook Events

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 { "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" {} } } getsubscriptionbyid { "data" { "id" "string", "description" "this is a sample subscription", "topic" "sample topic name", "eventappid" "string", "events" \[ "event1", "event2" ], "webhook" { "url" "https //example com/webhook" }, "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 { "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" } } here is a sample response for the createsubscription request createsubscription { "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=" } } 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" ] } 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" ] }