Webhooks

More about Webhooks

Subscribing to notifications

You can choose which topics (or event flows as we call them) you're interested in when requesting an APP. Of course, you can also edit your existing apps to subscribe or unsubscribe to event flows.

To subscribe to a flow you need to provide the information required when requesting an APP.

Notification format

All notification messages conform to a standard format, as shown here:

		JSON

{
  "transaction_id": "e9a0b0c8-6aad-4a63-8679-501bd2d28761",
  "object_id": "9de9b5e3-1720-11e8-8790-0242ac110002",
  "destination": "https://myawesomeapp.com/webhooks",
  "timestamp": 1517236809256,
  "event_timestamp": 1517236809256,
  "flow": "publish_advert",
  "event_type": "advert_posted_success",
  "error_message": "",
  "data": { ... }
}

Copied to clipboard

Note that the data field will contain data that are specific to any given notification, so its content will vary accordingly. This is important because your application must be prepared to deal with those situations. Here's a brief explanation of each field in this payload:

Field	Description
transaction_id	The unique identifier of the message. It is used to identify and track the flow of requests within the API
object_id	The unique identifier of the data - for instance, if the flow is an export of an advert, the object_id would be the identifier of the advert being exported
destination	The registered callback url of the subscriber (the URL to which this message will be sent)
timestamp	The timestamp of what the event describes (the state change, the message creation, etc.) in milliseconds
event_timestamp	The date of the creation of the event (in milliseconds)
flow	The name of the flow to which this notification refers to
event_type	The event that triggered the notification
data	Additional data related to a given notification

Notice that all requests made by our API to the configured endpoint will use the header "user-agent" with the value "olx-group-api".

Additionally, a custom header named x-signature will be present for each notification, containing an Hexademical HMAC (using SHA1) signature of the object_id and transaction_id in the following format: <OBJECT_ID>,<TRANSACTION_ID>

According to this, for the previous notification example and assuming you have provided the word "mywonderfulsecret" as your application's secret, the x-signature header would be:
a7b00386657384a3738d45462749d5a1b0ebd1e7

Check the section Signature validation to learn how to calculate the HMAC for notification such as the one above in different programming languages (Java, PHP, Go, C# and Python).

Signature validation

All the following examples assume that:

"signatureHeader" contains the "x-signature" header value
"notification" is a variable of a class that represents the notification structure
"secret" contains the secret configured for your application

		Java

package com.olx.example;

import com.olx.ecosystem.util.HmacSha1SignatureUtil;
import java.security.GeneralSecurityException;
import java.util.Objects;

public class Client {

  private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";
  
  public void handleNotification(final String signatureHeader,
    final WebhookNotification notification, final String secret)
    throws GeneralSecurityException {
    String toSign = String.format("%s,%s", 
      notification.getObjectId(), notification.getTransactionId());
    String signature = calculateRFC2104HMAC(toSign, secret);
    if (!Objects.equals(signature, signatureHeader)) {
      throw new SecurityException(
        "Signature in header (" + signatureHeader + ") does not match expected signature (" + signature + ")");
    }
    ... // do whatever you need to do with this notification
  }

  private String calculateRFC2104HMAC(final String data, final String key) throws GeneralSecurityException {
    if (data == null || StringUtils.isBlank(key)) {
      return null;
    }
    Key signingKey = new SecretKeySpec(key.getBytes(), HMAC_SHA1_ALGORITHM);
    Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
    mac.init(signingKey);
    return Hex.encodeHexString(mac.doFinal(data.getBytes()));
  }
  
  ...
}

Copied to clipboard

Available event flows

Event flows are basically groups of events. Here are the ones currently available and a small explanation about when they are triggered: