Events

Subscribe to events

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 /event endpoint, the system will automatically forward the event as a JSON HTTP POST request to the provided URL.

POST

/event/subscription

Subscribe to events

curl --request POST \
  --url https://api.catch-e.com/event/subscription \
  --header 'Authorization: <api-key>' \
  --header 'Audit-User-Id: <string>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "callbackAuthentication": {
    "apiToken": {
      "headerName": "<string>",
      "token": "<string>"
    },
    "basic": {
      "password": "<string>",
      "username": "<string>"
    },
    "oauth2": {
      "clientId": "<string>",
      "clientSecret": "<string>",
      "grantType": "client_credentials",
      "password": "<string>",
      "scope": "<string>",
      "tokenUrl": "<string>",
      "username": "<string>"
    },
    "type": "oauth2"
  },
  "callbackParameters": {},
  "callbackUrl": "<string>",
  "description": "<string>",
  "sourceSubscriptionId": "<string>",
  "types": [
    "<string>"
  ]
}
'

{
  "subscriptionId": "<string>"
}

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),
}

The POST request will also include an x-payload-signature HTTP header containing a base64-encoded RSA signature of the payload. This signature can be verified using the certificate located at the signingCertURL provided within the message payload.

The signingCertURL must include https://api-event-keys.catch-e.com.au

The API response includes a subscriptionId, which can be used later to remove the subscription.

This method requires the Events:Subscribe permission to be associated with your role.

Authorizations

Authorizationstringheaderrequired

For accessing the API a valid token must be passed in all the queries in the 'Authorization' header.

A valid token is generated by the API and returned by the /authenticate method by supplying a valid username and password.

The following syntax must be used in the 'Authorization' header :

Bearer aaaaaa/bbbbbb.ccccccc.dddddd

Headers

Audit-User-Idstringheader

(Optional) User Id to use for audit purposes. This header requires the Audit:UserIdOverride permission to be associated with your role.

Maximum string length: 5

Pattern: ^[1-9]{1}[0-9]*$

Body

callbackAuthenticationobject

Configuration for authenticating requests sent to the callback URL.

Show child attributes

callbackParametersobject

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

callbackUrlstringrequired

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

descriptionstring

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

sourceSubscriptionIdstring

An optional source subscription id filter. This is applicable when subscribing to event subscriber processing events.

typesstring[]required

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

Minimum array length: 1

Response

Subscription created

subscriptionIdstringrequired

An ID representing the unique subscription entry. This ID can be used to delete the subscription later.

Still need help? Ask the team