Register and Configure Webhooks

Instant ID as a Service allows Enterprise tenants to use webhooks that automate notifications to external systems through Entrust APIs when specific resources are created, updated, and deleted. Configuring specific webhook events to resources determine notification types sent to the chosen destination. This feature keeps other applications synchronized with key resource activities. Refer to the following list of available resource and event types for Instant ID as a Service:

Resource Type Event Type Definition
credential credential.create Notify when a new credential is created.
credential.update Notify when a credential is updated.
credential.delete Notify when a credential is deleted.
credential.print

Notify when the credential is printed. To be used for performing a pre-print operation. The notification will contain the print job ID, which needs to be used by the customer's integrated system to resume printing.

For more information about the Resume Print API:

  1. Go to Issuance API Guide at Developer > Issuance API Guide.

  2. Go to APIs > Issuance > PrintAPI > Resume a print job after pre print operation.

Note: Instant ID as a Service webhooks are restricted to tenants using the Enterprise entitlement bundle. For information on Entitlement bundles, refer to About Account Entitlements. Enterprise tenants must have Webhook Management permissions enabled. To enable or modify permissions for a role, refer to Create and Manage Roles. Enterprise tenants must also create an Issuance (Administration) API application. For instructions, refer to Add an Issuance API.
Note: Instant ID as a Service allows 20 active webhooks per Enterprise tenant.

Use the following instructions to register and configure webhooks for automated resource notifications:

Register a Webhook

Webhooks must be registered with a specific resource. Use the following instructions to register a webhook:

  1. Navigate to Main Menu Main Menu > Administration > Resources > Webhooks. The Webhooks page opens.

  2. In the Webhooks section, click Add to register a webhook. The Register a Webhook dialog box opens.

  3. In the Callback URL field, enter the secure HTTPS URL (e.g., https://example.com/webhook) or IP address (e.g., https://123.123.123.123) where resource notifications will be sent. This URL directs Instant ID as a Service where to deliver webhook event data.
    Note: All customer callback URLs must use the HTTPS protocol with TLSv1.2 and TLSv1.3 supported. Versions lower than TLSv1.2 are not supported. An error message will appear if the server doesn't use the supported TLS versions.

    Note: The callback URL is public.

  4. (Optional) In the Expiration field, enter the number of days the webhook should remain active. This limit determines how long Instant ID as a Service will continue sending notifications to the callback URL before the webhook expires. If "0" is entered, the webhook will not expire.

  5. In the Webhook Events section, search for the resource being configured for the webhook in the Quick filter... field.

  6. Under the Resource column, choose the searched resource and select the desired webhook event options by checking the appropriate boxes:

    • Create: Notify when a new resource is created.

    • Update: Notify when an existing resource is updated.

    • Delete: Notify when an resource is deleted.

    • Print: Notify when the credential is printed. To be used for performing a pre-print operation before printing.

    • All: Select all options (Create, Update, Delete, and Print).

  7. Click Add. A "Webhook successfully registered!" message displays.

Manage an Existing Webhook

Once a webhook is registered, existing webhook properties can be configured. Use the following optional instructions to manage existing webhooks:
Note: You can view your webhook token when accessing an existing webhook. The webhook token is auto-generated after the webhook has been registered, and is used to verify the outgoing requests to the client. The webhook token value should be stored securely in order to verify the webhook requests to their server.
Note: If a webhook expires, create a new one with the callback URL and events used previously.

  1. In the Webhooks section, click the URL of the desired webhook. The Manage Webhook dialog box opens.

  2. Click Copy to Clipboard to copy the webhook token to your clipboard.

  3. Click Show to reveal the webhook token.
  4. Adjust the Activate slider button to activate or disable the webhook.

  5. In the Callback URL field, edit the secure HTTPS URL.

  6. In the Webhooks section, select the check box for the desired webhook(s) and use the following options:
    • Click Disable to disable the webhook.
    • Click Enable to enable the webhook.
    • Click Test Webhook to send a test payload to the callback URL, verifying that the server is ready to accept webhook notifications.
      Note: Webhooks must be registered before testing them.
    • Click Delete to delete the webhook.

  7. In the Webhook Events section, search for the resource being configured for the webhook in the Quick filter... field.

  8. Under the Resource column, choose the searched resource and select the desired webhook event options by checking the appropriate boxes:

    • Create: Notify when a new resource is created.

    • Update: Notify when an existing resource is updated.

    • Delete: Notify when an resource is deleted.

    • Print: Notify when the credential is printed. To be used for performing a pre-print operation before printing.

    • All: Select all options (Create, Update, Delete, and Print).

  9. Click Save. A "Webhook successfully registered!" message displays.

Verify Webhook Notification Delivery

After registering and configuring a webhook, the notification delivery audit will be available either via the test webhook option or the resource update. You can view if your webhook successfully receives notifications to its endpoint by viewing the webhook notification delivery status in the Instant ID as a Service audit log. Use the following instructions to access a webhook record in the audit log.

  1. Navigate to Main Menu Main Menu > Dashboard. The Dashboard page opens.

  2. Click the Authentication, Issuance, or Management radio button to set the type of audit log you want to view.

  3. Click the row for the specific audit log you want to view. The Audit Event page opens.

  4. Under Entity Attributes, verify that the webhook payload attributes are accurate.

  5. Click OK.

  6. Verify if the webhook payload has sent to the callback URL with either a pass or fail .

Note: Upon sending a webhook notification, acknowledge server response success by receiving an HTTP 200 OK status code within 15 seconds. Otherwise, Instant ID as a Service will attempt to resend the notification a maximum of 5 times. If a retry fails on the 5th attempt, the webhook will be disabled. The retry schedule applies if the client URL is no longer reachable or a 200 success response is not provided within 15 seconds. For more details, refer to the following retry schedule:

  • 30 seconds after the first attempt

  • 2 minutes after the first attempt

  • 15 minutes after the first attempt

  • 2 hours after the first attempt

  • 10 hours after the first attempt

Webhook Signature Verification

Webhook signature verification ensures that Entrust securely and validly delivers the webhook payload to the client server without interference. When a payload is sent, it includes a unique signature in the request header and is created with a secret key shared between the sender and receiver.

For instructions on verifying webhook signatures, see the IDaaS developer documentation:

  1. On the top-right of the main menu, navigate to > Developer > Issuance API Guide. The IIDaaS Developer Hub opens.

  2. Click the Docs tab.

  3. Click Webhook Signature Verification. The Webhook Signature Verification guide opens.
    Note: Java, C#, Python, and Node.js code samples are available.

Webhook Payload Schema

For instructions on webhook payload schema, see the IDaaS developer documentation:

  1. On the top-right of the main menu, navigate to > Developer > Issuance API Guide. The IIDaaS Developer Hub opens.

  2. Click the Docs tab.

  3. Click Event Payload Schema. Additional attributes present for certain webhook events payload are specified under the "Additional attributes in payload for certain events" section.

Fetch Webhook Resource Details

After a verifying the webhook signature, retrieve the latest details of the associated resource. This is done by parsing the event body to extract the resource's unique identifier and sending a request to the corresponding API endpoint.

For instructions, see the IIDaaS developer documentation:

  1. On the top-right of the main menu, navigate to > Developer > Issuance API Guide. The IIDaaS Developer Hub opens.

  2. Click the Docs tab.

  3. Click Webhook Signature Verification. The Webhook Signature Verification guide opens.

  4. Navigate to the "Fetching updated resource details" section.
    Note: Java, C#, Python, and Node.js code samples are available.

Pre-Print Webhook

The Pre-Print Webhook in Instant ID as a Service sends notifications for specific pre-print events to an external system via webhooks so users can independently manage card creation or enrollment based on real-time updates via the UI or API. The webhook notifies the external system when a print request is initiated. This webhook allows the external system to retrieve, modify, and update enrollment data before triggering the Print Enrollment API (POST) to finalize the printing process in Instant ID as a Service. For example, smart card encoding data can be passed via the API.