Notifications

Highnote provides notifications that allow you to react to and respond to events in your Highnote integration. The following use cases are commonly used for notifications:

• Interact with asynchronous onboarding flows
• Monitor changes and alerts
• Transfer data into third-party systems

Notification schemas can change over time. When new attributes are added, Highnote will notify you seven days before release. When a breaking change occurs, Highnote will notify you 90 days before release to ensure ample time for any necessary updates.

To maintain uninterrupted service, we recommend building robust and resilient integrations that can adapt to these changes.

Highnote notifications use webhooks to deliver events to your system. Refer to the following guidelines for using webhooks:

• Webhooks can be managed using the Highnote API or the dashboard
• You can have up to 50 active webhooks at a time
• You can configure specific events to be delivered to each webhook

Notification events are sent as POST requests with JSON bodies. Highnote will send the following headers on each request:

• user-agent: HighnotePlatform/1.0.0
• highnote-signature: The result of computing an HMAC 256 signature of the request body
• highnote-replay: This will be sent in cases where the event is being manually re-delivered
• content-type: application/json

We recommend using the following best practices to ensure your webhooks remain secure and maintain functionality with your integration.

You can ensure events pushed to your webhook are coming from Highnote by inspecting the signature header or metadata.

The signature of the payload will be in the highnote-signature HTTP header. The header contains a comma-separated list of signatures. Usually, the list will only contain one item unless you are rolling your signing key.

To verify the signature with the payload you received, start by signing the payload you receive using your language-specific HMAC signing library and the signing key secret for your notification target. The payload Highnote sends you includes a timestamp, so there is no need to concatenate any additional information.

Once you have a local signature, you can extract the value of the highnote-signature and compare the two using a timing safe equals operation.

The following code sample displays how this would look in node.js:

Copy code snippet
import { timingSafeEqual, createHmac } from "crypto";

function verifySignature(
  secret: string,
  payload: string,
  remoteSignature: string
): boolean {
  const localSignature = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return timingSafeEqual(
    Buffer.from(remoteSignature),
    Buffer.from(localSignature)
  );
}

If there is equality between the signatures, you can verify the timestamp of the event is within a certain threshold. The signature timestamp can be found in the payload at $.extensions.signatureTimestamp, with the value being the number of milliseconds since Unix epoch.

Copy code snippet
function within15minutes(payload: string): boolean {
  const jsonPayload = JSON.parse(payload);
  const { signatureTimestamp } = jsonPayload.extensions;
  return (Date.now() - signatureTimestamp) <= 15 * 60 * 1000;
}

Sometimes, webhook endpoints may receive duplicate events. To prevent processing duplicate events, you should implement idempotent event handling. This can be done by maintaining a log of all processed events and not processing events that have already been logged.

You can add webhooks using the addWebhookNotificationTarget mutation. For more information on this mutation, see addWebhookNotificationTarget in the API reference.

The requirements for an HTTP webhook are:

• The endpoint must be served via HTTPS
• Must return a 2XX status code. All other status codes will be considered a delivery failure and the request will be retried

The following process outlines how a webhook is verified and activated:

1. When a webhook is created, the status updates to PENDING_VERIFICATION.
2. Highnote delivers a NOTIFICATION_ACTIVATION event to your webhook, which is a test event.
3. Upon receiving a 2XX response to the test event, the status updates to ACTIVE.
4. If the webhook does not return a 2XX response, the status remains in PENDING_VERIFICATION. You can attempt to activate the webhook using the activateNotificationTarget mutation.

For testing, if you do not have a server, you can use webhook.site, requestbin, or pipedream. Do not use these services for your production webhooks.

Use the following mutation to add a webhook:

Highnote handles notification failures and retries as follows:

• NOTIFICATION_ACTIVATION events are retried two times (three total attempts) within a minute for both test and live environments.
• All other notifications are retried three times (four total attempts) in the test environment and nine times (10 total attempts) in the live environment with exponential backoff.

If a notification fails all attempts, we will disable the webhook target. You must manually reactivate it through the API or dashboard. If your webhook endpoint is down or if you miss any events, you can retrieve them via the API.

Use the following query to view delivery attempts. When querying notification events, you can also see the delivery attempts in the response. The value will be null if no target is enabled for this event type.

You can use the GetUnsuccessfulWebhookNotificationTargetEvents query to retrieve failed notifications. This is useful when your webhook endpoint is down and, as a result, deactivated. For more information on retries and failures, see Retries and Failures.

Once you have retrieved any failed notification events, you can replay them using the replayNotificationEvent mutation. You can also use this mutation to manually re-deliver events to your webhooks.

You can update the name of a notification target without affecting the delivery of events using the following mutation:

Deleting a notification target may impact the functionality of your Highnote integration and cannot be reversed.

Notification targets may be deleted. Deleting a target will stop the delivery of all events because the notification target will no longer exist. Use the following mutation to remove a notification target:

Once a target is deactivated, any attempts to send notifications to the target will return an error status.

A webhook with a DEACTIVATED status for more than 30 days is considered expired. Such webhooks will be deleted and will no longer be visible.