Skip to main content

Webhooks

Webhooks allow your application to receive asynchronous notifications from the Entrupy API when certain events occur in your account. This is more efficient than polling the API for changes.

Configuration​

To use webhooks, you must configure an endpoint in your application that can receive HTTP POST requests from Entrupy. When creating a webhook subscription via the API, you will need to provide:

  1. Endpoint URL: The publicly accessible URL where Entrupy will send event notifications.
  2. Secret Key: A secret string that Entrupy will use to sign the webhook payloads. You will use this same secret to verify the authenticity of incoming requests.

Entrupy supports multiple webhook subscriptions per account, allowing you to, for example, use different endpoints for your staging and production environments.

When an event you've subscribed to occurs, Entrupy will send a POST request to your configured URL. The request body will be JSON, and an Entrupy-Signature header will be included. You must verify this signature using the HMAC-SHA256 algorithm with your shared secret key to ensure the request originated from Entrupy and was not tampered with.

Events​

The Entrupy API emits webhook events for key lifecycle changes. Current events include:

  • session.completed – Fired when an authentication or fingerprinting session has finished processing. The payload will contain details about the session and its outcome.
  • support.message – Triggered when a new structured support message is available for an item involved in an authentication. This allows you to promptly update your internal systems or notify users.
  • certificate.transfer – Sent when a certificate transfer has been initiated or its status has been updated.

Additional events may be added as the API and product features evolve. Always refer to the API reference documentation for the most up-to-date list of events and their payload structures.

For an example of how to implement a server to receive and validate these webhook notifications, see the Example Webhook Endpoint Server.