​
Incoming Webhooks with PassEntry

​
Overview

When building integrations with PassEntry, you might want your application to receive events as they occur, so that your backend systems can execute actions accordingly. To enable webhooks, you must first register a valid HTTPS URL, and subscribe to the events you want to be notified by. To do this, please visit the Webhook section on the PassEntry dashboard.

​
Setting Up Your Webhook Endpoint

  • HTTPS Requirement: Ensure your endpoint is a valid HTTPS URL and the path can receive POST requests.

​
Receiving Webhook Events

  • Event Notification: Upon the occurrence of a subscribed event, PassEntry will send a JSON payload to your endpoint, detailing the event type, timestamp, and relevant information.

​
Security Measures

We implement a number of security measures to guarantee any interactions between PassEntry and your system are verified and authentic.
  • Secret Key: When configuring your webhook endpoint, you will be provided a secret key, which PassEntry will use to sign any outbound webhooks. You must store this securely. If you believe your secret key has been compromised, you have the option to rotate your secret key. This will immediately invalidate the previous secret key and sign all subsequent webhooks with the new key
  • Timestamp: Each webhook payload includes a timestamp, serving as a safeguard against replay attacks.
  • HMAC-SHA256 Signature: Every outgoing webhook includes an HMAC signature. The signature is included in the X-Webhook-Signature header and is generated using the webhook payload and the shared secret key. To verify that the webhook is authentic, you can encrypt the webhook payload using the SHA-256 encryption algorithm and your secret key. If your generated signature matches the signature included in the X-Webhook-Signature header, you can confirm that the webhook is authentic.

​
Reliability and Retries

  • Asynchronous Delivery: Webhooks include a timestamp to reflect the actual event time.
  • Retry Mechanism: Failures in delivery due to network issues, SSL problems, or non-2xx HTTP responses will trigger retries. PassEntry retries delivery up to 10 times over 3 days, using exponential backoff.

​
Responding to Webhooks

  • Success Responses: Please ensure your endpoint returns a status code within the 200-299 range. Any code outside this range is considered an error, prompting retries.
  • Response Body: While optional, you may return a response body.

​
Example Success Response

HTTP Status: 200
Content-Type: application/json

{
"status": "ok"
}