deft/Cisco.tmpKb63qr.org

Cisco Notes

• DI/CSC Webhooks

DI/CSC Webhooks

For DI:

1. everytime an admin log in, DI will check and create a webhook for its org
2. everytime anyone of this org change a module instance the webhook is triggered to inform DI a module instance changed.

The HTTP call will be auth by whatever mean is preferable. Basic Auth is possible, as well as API Token or even iroh-jwt. But iroh-jwt is not mandatory, this is up to DI.

For CSC:

1. We (the admins of IROH) create a global webhook
2. Everytime anyone from any org change a module instance the webhook is triggered

For CSC the webhook must be configured to use a client-id. With a configured client-id, we will generate an access token (using the iroh-auth implementation that will perform a lot of checks).

Note: As we want the webhook to work for every user, the client for CSC must be trusted (by us admin). It means, that the access token creation will almost always be successful.

Warning: If a client-id is configured then the body should contain a field access_token with the built access token (the function gen-access-token-resp should take care of this part of the body). Note you might also potentially want to provide an id_token in the body.

Remark: It is important to separate the Authentication concern from the data send by the webhook.

The webhooks should support different type of authentication that could potentially be changed without affecting the content of the webhooks. So the webhook should be able to use:

• basic-auth
• api token
• iroh-jwt

In order to use iroh-jwt the webhook MUST configure a client-id that will be used to generate access tokens, ideally the client-id will have a configured audiences. I do not have an opinion on the subject, but I could imagine there could be a decorelation between the client-id used to use a JWT to call the webhook endpoint and the client-id that will be used to generate the access token in the body. I think using a single client-id in the webhook configuration is fine.

The important point being that, one should not expect the webhook endpoint to use the access token in their Authentication header but only the access token in the body.

Ideally, the webhook http call should contain as much information as possible about the event. Typically:

{:user {:user-id ,,, :user-email ,,,} ;; <- the person that triggered the event
 :org {:id ,,,} ;; <- the org of the triggerrer
 ;; metas about the webhook itself so the endpoint know how to find/update/delete a webhook
 :webhook-creator {:user {:user-id ,,,}
                   :org {:org-id ,,,}}
 ;; in case the webhook contain a client-id configuration the token generated via this client
 :token {:access-token "...."
         :token-type "bearer"
         :scopes [,,,]
         :expires_in 300}
 ;; the event type (I havent double check the schemas, but I guess there is somethign similar)
 :type :module-instance-update
 ;; the details about the event
 :data {:module-instance-id ,,,
        :diff {,,,}}
 }