Subscribe to presence updates

Notification API
1

How can I subscribe to presence status changes?

2

There’s some general information available here: Notification API Guide.

It’s recommended that you create a subscription to specific devices or users (aka the ‘principal’), to ensure that you’re not creating a subscription that generates unnecessary traffic. Here’s the general format for the request body that would create a subscription for presence changes on a specific user/device. All variables that would need to be populated by you are in braces:

{
    "applicationId": "{MyGuid}",
    "deviceId": "{MyURLtoSendNotificationsTo},
    "transport": "webhook",
    "topic": "platform-api-presence",
    "subjectFilter": "/presentities/{principalId}"
}

Let me know if that works!

3

Well, for our use case we would like to subscribe for all the users in the account. Is there a limitation to it?

4

Depending on how many users are involved and how they change presence, you might start running into performance problems (or cause them for us). I believe if you add a method filter, it might be helpful in reducing unnecessary traffic:

{
    "applicationId": "{MyGuid}",
    "deviceId": "{MyURLtoSendNotificationsTo},
    "transport": "webhook",
    "topic": "platform-api-presence",
    "subjectFilter": "/presentities/[^/]+$"
    "methodFilter": "PUT"
}
5

Hi @budd.renaud ,

What will be the correct “applicationId” value while creating the subscription? Is it the account Id or client Id of application or something else ?
https://developer.mitel.io/api-reference/notifications#operation/createSubscription

Also is there a way to add security header like verification-token for webhook’s during creating a subscription that can act as a measure for data security? Like a field which is set during subscription and is received in header with all webhooks matching that subscription to verify the request?

6

Hi @Aakash!

The applicationId is exactly what you’re looking for. It’s included in the header of the webhook, and you can generate it yourself. From the Notification API Guide:

ApplicationID - This is a unique ID specific to your app that’s required if you’re using a webhook (as opposed to a websocket). You can generate this yourself, just make sure it’s unique, so something like a 128-bit GUID is a good choice. The ApplicationID will be including in the header of the webhooks you receive as a signing key for trust purposes, so you can verify that the webhooks you receive are legitimate.

7

Hi @budd.renaud !

Thanks for letting me know about ApplicationId. As you mentioned, I created a subscription for Presentities with applicationId , like below

{
    "applicationId": "829e823f-f27e-47ee-a101-5d5e9c6266bf",
    "deviceId": "https://46ac33099954.ngrok.io/v1/domains/111/mitel/presence-webhooks",
    "transport": "webhook",
    "topic": "platform-api-presence",
    "subjectFilter": "/presentities/[^/]+$",
    "methodFilter": "PUT"
}

However, I did not receive applicationId in the header of webhook. Attaching the information I received

image
image861×398 57 KB

Do you think I am missing something ?

8

It appears I was incorrect about how the applicationId was used. I’m looking for a more detailed explanation, but here’s what I’ve been able to ascertain in looking through the code:

  • A webhook will contain a digital signature within the x-notify-signature header
  • The signature is created via an HMAC using sha256 as the algorithm and a configured webhook key (applicationId)
  • The body of the event is fed into the algorithm to be hashed and returned as a hex

The signature will then need to be validated before the webhook is handled:

  • Recreate the signature using the event body and configured webhook key (applicationId), as specified above
  • Compare provided signature with the recreated version to see if they match

The only thing that I’m not confident about is what EXACTLY constitutes the ‘event body’ here. I can’t seem to find where that’s defined, but the implication is that it’s just the body of the received webhook itself. You can test by using an HMAC-SHA256 generator or library (e.g. Crypto | Node.js v16.4.2 Documentation) and encode the webhook body using the applicationId as the key and see if it matches the content of the x-notify-signature header. You might need to ‘stringify’ the JSON first.

9

Thank you Budd,

In addition to security, checking a verification-token in header would avoid consuming the event body and additional processing making performance comparatively faster per webhook. For recreating the signature we would not only consume the event body and produce signature for each and every webhook we receive to validate, we may also add overhead to processing with every request which relays to delay in presence publishing real-time. This is in regards when we have many webhook per second.

Eventually, if it’s coming down to reading event body, then I see another field “context” (additional subn. info.) which is received back in the response body, but I think the point was to avoid using body in case of a malicious payload and also avoiding processing overhead.

10

If you’re planning to receive a large number of webhooks in a short period of time, perhaps websockets from the clients is the better approach here. Can you provide any information about your use case? I assume it pertains to presence. We can always setup a call to discuss if you’d prefer to avoid outlining it here in a public arena.

I will take your feedback to the team here, but given how this model is already being used by several Mitel applications built on the same APIs, it’s unlikely that we’ll see it change.

11

Yes, I think it’s better to discuss over a call. I would convey the same to the team and setup something.

Thank you Budd.