Skip to main content

Webhooks

Webhooks permits you to be notified when an event happens on fairjungle.

info

If you use an HTTPS URL for your webhook endpoint, fairjungle will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Setup​

Go to Admin Space, in Developers > Webhooks section.

info

As an alternative, you can manage webhooks programmatically using our API.

Click on Add webhook button and fill those infos:

  • URL: the endpoint URL where events will be sent
  • Description: a description of this webhook
  • Events: the list of event kinds to send

add webhook

A Secret Key is generated for that webhook. You can use that Secret Key to certify that the events sent to your webhook are issued by fairjungle.

webhook added

Carefully note the Secret Key value, as it is displayed only once.

webhooks

Event Notification​

A webhook notification is an event resource that contains informations about what just happened, including the kind of event and the data associated with that event.

Example:

{
  "id": "628b6efe7290e71a9e52d01b",
  "type": "event",
  "createdAt": "2022-05-23T11:24:46Z",
  "data": {
    "canceled": false,
    "createdAt": "2022-05-23T11:24:20Z",
    "exchanged": false,
    "id": "8e3df4c5-2070-4584-b91a-ef63b6394ef5",
    "kind": "rail",
    "rateId": "4f454c91-6654-4de8-8275-d54dcda59e62___trainline-itinerary-business-adddde0e-56ad-41e1-99b7-48b50fa943e8",
    "reference": "605515552196",
    "status": "succeeded",
    "tripProjectId": "8ec49117-68ce-4ba6-9a30-e0237e23f9b6",
    "type": "booking"
  },
  "kind": "tripProject.booking.succeeded"
}

To acknowledge reception of event, your endpoint must return a 2xx HTTP status code. All response codes outside this range indicate that you did not handle the event correctly.

info

If fairjungle does not receive a 2xx HTTP status code, the notification attempt is repeated. After multiple failures to send the notification, fairjungle marks the event as failed and stops trying to send it to your endpoint.

Signature​

Fairjungle signs the webhook notifications it sends to your endpoints by including a signature in the Fairjungle-Signature header. This allows you to verify that the events were sent by fairjungle.

The Fairjungle-Signature header contains a timestamp and a signature. The timestamp is prefixed by t=, and the signature is prefixed by s=.

Fairjungle-Signature: t=1590410028,s=8db0caf0c10c7a34ebd4dc98e73a7b7cd703ac34666e5bc892e52cdc6dbba0ba

Fairjungle generates signature using a hash-based message authentication code (HMAC) with SHA-256.

To verify the signature, you must:

  1. Extract the timestamp and signature from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a key and value pair.

The value for the key t corresponds to the timestamp, and s corresponds to the signature.

  1. Prepare the signed_payload string

The signed_payload string is created by concatenating:

  • The timestamp
  • The character .
  • The actual JSON payload
  1. Determine the expected signature

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

  1. Compare the signatures

Compare the signature in the header with the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.