Events

Events are the way Wompi informs you about something important that has happened without you actively requesting it, by using a webhook. In short, we will do a HTTP POST request to a URL that you specify, with a JSON that contains all the information related to the event that happened.

This way, for example, each time that a transaction is approved or rejected, Wompi will inform you about this activity on the event URL that you have setup on your account, so that you can implement the neccessary measures on your end (the business). You can setup the URL on our Commerce Dashboard.

A URL for each environment

Keep in mind that both in Sandbox and Production, you must set an events URL for each environment. This is done to avoid the accidental mix of Production and Sandbox data.

Handling an event

Each time that Wompi needs to notify an event to your system, it will use the event URL, with which it will make a HTTP POST request containing an object like the one shown below. Your system should respond to this HTTP request with a HTTP status 200 (the default successful response status of most popular frameworks and libraries). The response body that you send will not be important, because Wompi will not be using it in any way, so you can respond with an empty body, a JSON object, etc.

Whenever the HTTP status of your response is not 200, Wompi will consider that the event could not be notified correctly and will retry to notify the event again, maximum 3 times during the next 24 hours, until obtaining a 200 response. The first retry will be carried out 30 minutes later, the second one at 3 hours and the last one after 24 hours.

Use HTTPS

We recommend using HTTPS for the URL event that you specify. This guarantees that the information is encrypted from end to end and that nobody can modify it during the communication process.

Event body

Any event that Wompi sends you will always have the same structure:

{
  "event": "transaction.updated", // Name of the type of event
  "data": {
    // Event specific data
  },
  "sent_at":  "2018-07-18T08:35:20.000Z" // Exact date at which the event was notified the first time
}

For example, in the case of an event transaction.updated, which indicates that the state of a transaction has changed, the JSON body send to the event URL will look like the following:

{
  "event": "transaction.updated",
  "data": {
    "transaction": {
        "id": "01-1532941443-49201",
        "amount_in_cents": 4490000,
        "reference": "MZQ3X2DE2SMX",
        "customer_email": "john.doe@gmail.com",
        "currency": "COP",
        "payment_method_type": "NEQUI",
        "redirect_url": "https://mystore.com.co/payments/redirect",
        "status": "APPROVED",
        "shipping_address": null,
        "payment_link_id": null,
        "payment_source_id": null
      }
  },
  "sent_at":  "2018-07-20T16:45:05.000Z"
}

Event types

You will find a list of the types of events that Wompi uses. This list can grow later on, so we recommend re-reading it regularly.

Type	Description
transaction.updated	The state of a transaction has changed, usually to a final state (APPROVED, VOIDED, DECLINED or ERROR)
nequi_token.updated	The state of a Nequi token changed, usually to a final state (APPROVED or DECLINED)
bancolombia_transfer_token.updated	The state of a Bancolombia token changed, usually to a final state (APPROVED or DECLINED)

Security

To validate the information integrity notified to your event URL and avoid impersonations, Wompi uses an asymmetric cryptographic hash, its value is found in two place:

• The HTTP Header X-Event-Checksum.
• The checksum field from signature object.

We provide them in both places for convenience, so you are free to extract it from either one to make the respective security validation.

The used algorithm to generate this asymmetric sign is SHA256. The value of this checksum it's generated concatenating in order the following data:

• The values of the fields specified in the properties array, which point to fields in the data object.
• The timestamp field (integer) which is the event's UNIX Timestamp.
• A Secret, known only by the business and Wompi, which is available in the My account of the Commerce's Dashboard, below the Secrets of technical integration section. This secret must be kept with the utmost security on your servers.

Step by step: Verify the authenticity of an event

Following these instructions, we explain below how to calculate and validate, for example, the checksum of a Transaction Event, shown above, step by step.

Step 1: Concatenate the event data values

In the event signature object you must concatenate the data values described in the properties field. In this case, we have:

• transaction.id: Whose value is 1234-1610641025-49201.
• transaction.status: Whose values is APPROVED.
• transaction.amount_in_cents: Whose value is 4490000.

The value resulting from the concatenation of this data, following the order specified in the signature.properties array is:

1234-1610641025-49201APPROVED4490000

properties can vary. The values of the properties field can vary over time and in each event, so it is very important that you do not assume them as a fixed array within your code, but always extract them from the event and use them appropriately in each validation.

Step 2: Concatenate the timestamp field

To the concatenate of the properties shown in Step 1, you must also concatenate the timestamp field of the event, which in this case is 1530291411. The value that you should now have in the string at this point is:

1234-1610641025-49201APPROVED44900001530291411

Step 3: Concatenate your secret

In this step, you must concatenate your secret to the string you are generating up to this point. Let's assume, in this example, that your secret is:

prod_events_OcHnIzeBl5socpwByQ4hA52Em3USQ93Z

The Event Secret is different from the Private Key.

It is important to clarify that this Event Secret is different from your Private Key or Public Key. The final result of the concatenation should be:

1234-1610641025-49201APPROVED44900001530291411prod_events_OcHnIzeBl5socpwByQ4hA52Em3USQ93Z

Step 4: Use SHA256 to generate the checksum

With this data concatenated appropriately, it is time to generate the checksum using SHA256. Passing the string through this algorithm yields, for example, the following result:

3476DDA50F64CD7CBD160689640506FEBEA93239BC524FC0469B2C68A3CC8BD0

The way SHA256 is used to calculate this value varies depending on each programming language. However, the result should always be the same, given the nature of this secure asymmetric encryption algorithm. Here are some examples:

PHP

// How it's written
hash ("sha256", $concatenated_string);
// Example
hash ("sha256", "1234-1610641025-49201APPROVED44900001530291411prod_events_OcHnIzeBl5socpwByQ4hA52Em3USQ93Z");

Ruby

# How it's written
Digest::SHA256.hexdigest(concatenated_string)
# Example
Digest::SHA256.hexdigest("1234-1610641025-49201APPROVED44900001530291411prod_events_OcHnIzeBl5socpwByQ4hA52Em3USQ93Z")

Step 5: Compare your calculated checksum with the one provided in the event

By generating the checksum value on your server yourself, you can now compare it with the one that arrived in the event. If both are the same, then you can be sure that the information presented is legitimate and sent by Wompi, and not a spoof from a third party. Otherwise, you should ignore the event.