Skip to main content

1.8 Webhook Notification Service

Plug&Charge
Updated

 

A webhook enables our ecosystem to push real-time notifications to your backend systems. Webhooks Service uses HTTPS to send these notifications to your backend endpoint as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Hubject uses the Webhook Service to notify your backend system when some event happens in our ecosystem. Webhooks are particularly useful for asynchronous events like when a contract is created, or a root certificate expires.

The following figure provides a high-level overview of the interface concept of the webhook service. The service is subscribed to all relevant events within the ecosystem. The partners can register at the webhook service to observe assets in the ecosystem. Relevant events from the other ecosystem components are collected by the callback service and forwarded to the partner’s system.

mceclip0.png

 

Available Events

The following actions trigger the event notification. The messages are routed to the observing backends as noted.

mceclip1.png

API

The webhook service requires the partner to provide a simple payload service with a public endpoint to receive events as a POST request.

Error Handling

The webhook service has a retry mechanism in place - for HTTP 5xx Server Errors, Hubject will retry in 1-hour intervals, and after 4 days, Hubject will unload the event as a failed event.

Contract Payload Structure

Request: POST /payload-path HTTP/1.1
Host: your-payload-url.com
Headers:

Content-Type: application/json
X-Hubject-Signature: sha256=7808b566f4057216e64c6298bfd5a184d4d715ffec6599311e5266f48865XXXX
Body: 
{   
    "eventId": "caf56bee-f90d-4e81-a862-7e0d0f21d306",
    "eventType": "oem.contract.created",
    "payload": {
        "emaid": "EMAID",
        "pcid": "PCID",
        "contractCert": "CONTRACT_CERTIFICATE_BASE64"
} }

Root Payload Structure

Request: POST /payload-path HTTP/1.1
Host: your-payload-url.com
Headers:

Content-Type: application/json
X-Hubject-Signature: sha256=7808b566f4057216e64c6298bfd5a184d4d715ffec6599311e5266f48865XXXX
Body: 
{   
    "eventId": "xxxxx",
    "eventType": "root.cert.added",
    "payload": {
         "rootCertificateId": "xxxxx",
         "distinguishedName": "xxxxx",
         "commonName": "xxxxx"
} }

Validating Payloads from Hubject

Hubject can optionally sign the webhook events it sends to your endpoints by including a signature in each event’s X-Hubject-Signature header. This allows you to verify that the events were sent by Hubject, not by a third party.

In order to validate the signature, you will need a secret of your endpoint, you can find it when you create a new endpoint for the webhook or retrieve the endpoint from the Webhooks's backend.

Hubject generates signatures using a hash-based message authentication code HMAC with SHA-256. To prevent downgrade attacks, you can create a custom solution by following these steps:

Step 1: Prepare the message string

  • Get the actual JSON payload (i.e., the request body)

Step 2: Determine the expected signature

  • Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the Request body string as the message.

Step 3: Compare the signature

  • Compare the signature in the header to the expected signature.

For example, if you have a basic server that listens for webhooks, it might be configured similarly to this:

mceclip2.png

The recommended way is to calculate a hash using your webhooks secret, and ensure that the result matches the Signature from Hubject. Hubject uses an HMAC hex digest to compute the hash, so you could reconfigure your server to look a little like this:

mceclip3.png

mceclip4.png

Java Example

mceclip5.png

mceclip6.png

NOTE: Using a plain == operator is not advised. A method like secure_compare performs a "constant time" string comparison, which helps mitigate certain timing attacks against regular equality operators.

 

Status Code

These are the HTTP status codes that will be expected:

For a successful notification:

  1. 200 – OK
  2. 201 – Created
  3. 202 - Accepted

In those cases, the notification process stops.

 

For an Error case:

  1. 400 – Bad Request
  2. 404 – Not Found
  3. 409 - Conflict

In those cases, the notification process stops.

 

Any other error code will be a retry case:

  1. The notification will be retried every hour.
  2. The maximum retry period is 4 days.
  3. After 4 days, the notification process stops and no more retires are made

Related articles