Skip to main content
Contract Events APIs

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

Parameters - Path Variables

Key

Format

Notes

Mandatory

types

string

A list of event types the client wishes to subscribe to. The callback URL will be subscribed to all specified types.

Yes

sourceSubscriptionId

string

An optional source subscription id filter and in most cases will not need to be defined.

This is only applicable when subscribing to event subscriber processing events.

No

description

string

An optional description of the subscription callback's purpose. This is useful for identifying the associated systems or processes that consume events from the subscription.

No

callBackUrl

string($uri)

The publicly accessible HTTPS endpoint to receive event notifications. Must support POST requests.

Yes

callBackParameters

description

Additional parameters to be included in the message payload supplied to the callback.

No

Headers

Key

Format

Notes

Mandatory

Audit-User-Id

string

Pass a user_id here to create audit records with this user's details.

This can only be done if the authenticated API user has Roles / Apis checked for the permission Audit:UserIdOverride

No

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.