Webhooks

Webhook Events are notifications triggered by specific operations to which you can subscribe, allowing you to be alerted when those operations occur. These events might include scenarios such as a Network Token being updated, a successful 3DS session, or the completion of a function deployment. Each event is categorized by a type that defines the nature of the event, along with associated data relevant to that event.

Webhook Event Object

When an event is triggered, Evervault creates a new Event object, which is sent to your Webhook Endpoint as a JSON payload. This payload includes the following fields:

• id: A unique identifier for the event.
• type: The type of event that occurred (e.g. payments.network-token.updated or payments.3ds-session.success).
• data: This field contains the event-specific details.
• createdAt: An epoch millisecond timestamp marking when the event was generated.

Example Event Object

The following example Event Object is triggered when an update occurs on a Network Token:

Webhook Event Delivery

Webhook Events are delivered to a Webhook Endpoint via a POST request over HTTPS. The request includes a Content-Type header set to application/json. A Webhook Event is deemed successfully delivered when the Webhook Endpoint responds with a 2XX HTTP status code.

Single delivery is not guaranteed, and in rare cases, a Webhook Event may be delivered more than once. To handle potential duplicates, you can use the id field in the event payload to identify and filter out duplicate events.

You can register a Webhook Endpoint either through the Evervault dashboard (Settings Section) or via the Evervault API. An Evervault App can have multiple Webhook Endpoints registered, with each endpoint subscribed to a specific set of events.

Retries

If the Webhook Endpoint does not respond with a 2XX status code, Evervault will automatically retry sending the event using an exponential backoff strategy, gradually increasing the delay between each retry. This process continues until the event is successfully delivered or until 5 days (120 hours) have passed. If the event cannot be delivered within this timeframe, it will be permanently discarded.

Monitoring

You can monitor Webhook Event deliveries through the Evervault Dashboard, under the Logs tab. The logs include detailed information about each event, such as timestamps and status codes, enabling you to quickly diagnose and address delivery issues.

Getting Started

1. Deploy a new API Endpoint

To start receiving Webhook Endpoints, you need to set up an API endpoint within your infrastructure that can handle POST HTTP requests and process JSON objects. This endpoint must return a 2XX HTTP status code upon successfully completing the event processing.

In this example, we are creating a new endpoint, https://hooks.acme.com/evervault, specifically designed to handle Network Token updates.

2. Secure your Webhook Endpoint

All Webhook Event requests are signed using a secret key, allowing you to verify that the event was sent by Evervault. Each request includes a JSON Web Token (JWT) in the X-Evervault-Signature header, which you can use to authenticate the request. To do this, compare the signature provided in the header with a signature you generate locally using the payload and endpoint URL.

The signature is created by generating a SHA-256 hash of the body of the request. This hash, along with the endpoint URL, is then signed using the ES256 algorithm (ECDSA with a P-256 curve) and a private key. To verify this signature, use the corresponding public key, which you can retrieve from Evervault’s JSON Web Key Set (JWKS) endpoint.

Below are examples of how to verify an Evervault webhook signature using Node.js, Python, Go and Ruby. For optimal performance, it’s recommended to cache the JWKS instead of fetching it with each request.

3. Register your Webhook Endpoint with Evervault

After deploying your new endpoint, you can register it as a Webhook Endpoint with Evervault through either the Dashboard (Settings > Webhooks) or the Evervault API. You’ll need to subscribe this endpoint to the specific events you wish to receive. Once subscribed, Evervault will send those events to the registered endpoint whenever they occur for your app.

In this example, we are registering the newly created endpoint, https://hooks.acme.com/evervault, to listen for the payments.network-token.updated event.

Webhook Event Samples