Webhooks

Overview of webhooks

Webhooks allow you to subscribe to events which happen within CreateTOTALLY.

You can create as many webhooks as you like, supplying an event type and URL for each.

When an event happens in CreateTOTALLY, we will POST the data to the URL supplied by you.

See the API Reference for details of how to create webhooks.

Payload

Here's an example notification payload which will be sent in the body of the request:

{
    id: 'b7087263-5c3d-5032-b3ab-2896e27bc760',
    createdAt: '2022-05-11T13:37:10.148Z',
    type: 'analysis-job-completed',
    payload: { analysisJob: { id: "G_RpaIBkQwzkDrZVtBw96", status: "completed" } },

    Type: 'Notification', @deprecated
    MessageId: 'b7087263-5c3d-5032-b3ab-2896e27bc760', @deprecated
    Message: '{"analysisJob":{"id":"G_RpaIBkQwzkDrZVtBw96","status":"completed"}}', @deprecated
    MessageAttributes: { type: { Type: 'String', Value: 'analysis-job-completed' } }, @deprecated
    Timestamp: '2022-05-11T13:37:10.148Z', @deprecated
}

The type can be used to determine the type of notification.

The payload will contain the relevant information about each event.

@deprecated fields could be removed in future releases

Events

automation-asset-upload-completed

This is sent when an automation asset has been uploaded successfully.

Here's an example message body:

{
  "automationAsset": {
    "id": "A_RpaIBkQwzkDrZVtBw99",
    "processingStatus": "completed",
    "externalId": "your-internal-refererence"
  }
}

From here, you can use the automationAssets query to fetch the latest data.

automation-asset-upload-failed

This is sent when an automation asset has failed to upload.

Here's an example message body:

{
  "automationAsset": {
    "id": "A_RpaIBkQwzkDrZVtBw99",
    "processingStatus": "failed",
    "externalId": "your-internal-refererence"
  }
  "error": {
    "type": "system",
    "code": "automation-asset-upload-failed",
    "message": "File is too large"
  }
}

From here, you can use the automationAssets query to fetch the latest data.

analysis-job-completed

This is sent when an analysis job has completed successfully.

Here's an example message body:

{
  "analysisJob": {
    "id": "G_RpaIBkQwzkDrZVtBw96",
    "status": "completed",
    "automationAsset": {
      "id": "2q_ox8e_Qz5qcFrW5Fw3Z",
      "externalId": "your-internal-refererence"
      "availableModifications": []
    },
  }
}

From here, you can use the analysisJobs query to fetch the latest data.

analysis-job-failed

This is sent when an analysis job has failed.

Here's an example message body:

{
  "analysisJob": {
    "id": "G_RpaIBkQwzkDrZVtBw96",
    "status": "failed",
    "automationAsset": {
      "id": "2q_ox8e_Qz5qcFrW5Fw3Z",
      "externalId": "your-internal-refererence"
    },
    "error": {
      "type": "system",
      "code": "analysis-job-failed",
      "message": "File is too large"
    }
  }
}

automation-job-completed

This is sent when an automation job has completed successfully.

Here's an example message body:

{
  "automationJob": {
    "id": "A_ZpaIBkQwzkDrZVtBw61",
    "status": "complete",
    "apiRequest": {
      "externalId": "your-internal-refererence"
    }
  }
}

From here, you can use the automationJobs query to fetch the latest data.

automation-job-failed

This is sent when an automation job has failed.

Here's an example message body:

{
  "automationJob": {
    "id": "A_ZpaIBkQwzkDrZVtBw61",
    "status": "failed",
    "apiRequest": {
      "externalId": "your-internal-refererence"
    },
    "error": {
      "type": "system",
      "code": "automation-job-failed",
      "message": "File is too large"
    }
  }
}

From here, you can use the automationJobs query to fetch the latest data.

master-template-file-upload-completed

This is sent when a master template file has been uploaded successfully.

Here's an example message body:

{
  "masterTemplateFileUpload": {
    "id": "M_RpaIBkQwzkDrZVtBw96",
    "status": "completed",
  }
}

From here, you can use the masterTemplateFiles query to fetch the latest data.

master-template-file-upload-failed

This is sent when a master template file has failed to upload.

Here's an example message body:

{
  "masterTemplateFileUpload": {
    "id": "M_RpaIBkQwzkDrZVtBw96",
    "status": "failed",
  }
  "error": {
    "type": "system",
    "code": "master-template-file-upload-failed",
    "message": "File is too large"
  }
}

From here, you can use the masterTemplateFiles query to fetch the latest data.

Retries

If an initial delivery attempt does not result in a successful response from the subscriber, we will try to deliver the message again.

We attempt re-delivery for up to 2 hours using an exponential fallback function.

Below is an example of how this works in practise.

Attempt #	Timestamp
1	2022-06-05 11:22:55 (UTC+0200)
2	2022-06-05 11:23:06 (UTC+0200)
3	2022-06-05 11:23:46 (UTC+0200)
4	2022-06-05 11:24:17 (UTC+0200)
5	2022-06-05 12:20:29 (UTC+0200)
6	2022-06-05 13:14:50 (UTC+0200)

Please see the API Reference for more details on managing webhooks via the API.