CreateEventSubscription
CreateEventSubscription
Overview
This method is used to register a webhook (HTTPS callback URL) to receive notifications for one or more event types.
When an event matching one of the subscribed types is emitted via the emitEvent endpoint, the system will automatically forward the event as a JSON HTTP POST request to the provided URL.
On event dispatch, the callback URL will receive an HTTP POST payload with the following structure:
"messageId": (A unique Message Id GUID - example "367326e8-a25c-5704-8146-46250ac8fd68"), "timestamp": (ATOM date/time - example "2025-02-02T01:23:45.901Z"), "clientId": (Client Id - example "demo") "userId": (User Id - example "10000") "environment": (API environment - example "test") "eventType": (Event type - example "ping") "subscriptionId": (Subscription Id responsible for event dispatch) "signingCertURL": (Signing public certificate - used to verify x-payload-signature header), "message": (The payload JSON),
Included in this response is the subscriptionId which can be used in the API deleteEventSubscription.
Supplementary SWAGGER documentation is available here: https://api.test.catch-e.com/docs/?/Events/createEventSubscription.
Permissions
To run this API, the nominated 'web-services' role needs to be given permission.
If you are not actively using the API, leave the permission off for better security.
Go to Roles / Apis and check on Events:Subscribe
This API is not configured for external use but can be made available on request.
Contact Catch-e Support to request this update.
HTTP Method
Use the HTTP Method 'POST' for consuming this web service.
URL Examples
https://api.demo.catch-e.com/authenticate https://api.{{environment}}.catch-e.com/authenticate https://api.test.catch-e.com/event/subscriptonParameters - Path Variables
Headers
Body Sample
Create an Event Subscription
[ { "types": [ "receipts.batch.posted" ], "sourceSubscriptionId": "14729133173082437332", "description": "Run autoBuildClaims when a receipt batch is posted", "callbackUrl": "https://api.test.catch-e.com/event/job/sp/approvals/auto-build-claims", "callbackParameters": { "additionalProp1": {} } } ]Response Details
Successful Response Example
{ { "subscriptionId": "14729133173082439740"} }Error Response Examples
401 Unauthorized
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" }You have not authenticated before running this API or the token_timeout of the current session has passed. You need to authenticate again.
403 Forbidden
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" } You do not have permissions for this request. Go to System Roles and enter 'web_services'. Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.
Was this helpful?
More in Contract Events APIs
createContractEventspatchContractEventgetContractEventValuesgetContractEventDescriptionsStill need help? Ask the team