Webhooks

[Steinklo]

Hi,

I would like to know if it is possible to use webhooks to monitor changes on a refset member. Specifically, I need to be notified when a refset member is created, updated, or deleted.

Is this functionality supported, and if so, could you provide some guidance or examples on how to set this up?

Thank you!

Best regards,
David

[kaicode]

Hi David,

Snowstorm is able to make an HTTP call to an external service when any type of commit is made.

This can be enabled by configuring an HTTP endpoint using the service-hook.commit.url configuration item. Once this it set an HTTP POST will be made to the {service-hook.commit.url}/integration/snowstorm/commit with a request body like:

{
  "sourceBranchPath": "MAIN",
  "commitType": CONTENT,
  "headTime": 1716510064127
}

Where:

• sourceBranchPath is the branch that the commit is being made on
• commitType is one of CONTENT / REBASE / PROMOTION
• headTime is the commit timestamp

No specific details are sent about the content being changed during that commit. Perhaps if refset changes were being made on a specific branch this could be enough.

By default, when this the service hook is configured, Snowstorm commits will fail if the external service call results in non 2xx http response code. To disable this behaviour set service-hook.commit.fail-if-error=false.

There is a specific config item to block branch promotions if the service hook responds with an error: service-hook.commit.block-promotion-if-error This item defaults to false currently.

---

The alternative is to use the Traceability Service. This can be wired up to Snowstorm via a JMS queue, we usually use ActiveMQ for JMS but an AWS hosted queue should work.

The Traceability Service keeps a log of all content changes made on all branches. It can give detailed information for the changes made during a specific timespan or branch. Example:

{
  "content": [
    {
      "id": "tZMAqI8BUDO9AjcliNgs",
      "username": "xxx",
      "branch": "MAIN/AUTHORTEST/AUTHORTEST-525",
      "branchDepth": 3,
      "sourceBranch": null,
      "highestPromotedBranch": "MAIN/AUTHORTEST/AUTHORTEST-525",
      "commitDate": "2024-05-24T00:29:16.542+00:00",
      "promotionDate": "2024-05-24T00:29:16.542+00:00",
      "activityType": "CONTENT_CHANGE",
      "conceptChanges": [
        {
          "conceptId": "363847004",
          "componentChanges": [
            {
              "componentId": "5373564015",
              "changeType": "UPDATE",
              "componentType": "DESCRIPTION",
              "componentSubType": "900000000000550004",
              "effectiveTimeNull": true,
              "superseded": null
            }
          ]
        }
      ]
    },
    {
      "id": "u5MBqI8BUDO9Ajcl-Njr",
      "username": "xxx",
      "branch": "MAIN/AUTHORTEST/AUTHORTEST-525",
      "branchDepth": 3,
      "sourceBranch": null,
      "highestPromotedBranch": "MAIN/AUTHORTEST/AUTHORTEST-525",
      "commitDate": "2024-05-24T00:30:50.142+00:00",
      "promotionDate": "2024-05-24T00:30:50.142+00:00",
      "activityType": "CONTENT_CHANGE",
      "conceptChanges": [
        {
          "conceptId": "1340221003",
          "componentChanges": [
            {
              "componentId": "2ea61a0c-8f5a-44da-a253-7f638af1e09d",
              "changeType": "UPDATE",
              "componentType": "REFERENCE_SET_MEMBER",
              "componentSubType": "900000000000508004",
              "effectiveTimeNull": true,
              "superseded": null
            },
            {
              "componentId": "cba6fcb2-8c31-4c32-a341-f72561b71ab9",
              "changeType": "UPDATE",
              "componentType": "REFERENCE_SET_MEMBER",
              "componentSubType": "900000000000509007",
              "effectiveTimeNull": true,
              "superseded": null
            },
            {
              "componentId": "cde8c04d-e6d5-4494-854e-cc87b14b9a19",
              "changeType": "UPDATE",
              "componentType": "REFERENCE_SET_MEMBER",
              "componentSubType": "900000000000508004",
              "effectiveTimeNull": true,
              "superseded": null
            },
            {
              "componentId": "d7e98ba1-fc99-45f4-8d6f-29861a74b5f4",
              "changeType": "UPDATE",
              "componentType": "REFERENCE_SET_MEMBER",
              "componentSubType": "900000000000509007",
              "effectiveTimeNull": true,
              "superseded": null
            }
          ]
        }
      ]
    }
]

Here the componentSubType holds the reference set id.

Perhaps you might need both the service hook and Traceability Service to complete your solution.
Sorry it's not a straightforward single HTTP request with all the details. Let us know if you would like further guidance.

[kaicode]

If you wanted to keep things simple and deploy less components you could write something to receive the Traceability JMS payload directly. It's not HTTP like you hoped for but something like Apache Camel could receive the JMS request and forward it as an HTTP request to another endpoint.

[Steinklo]

Thank you!