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 setip on your account, so that you can implement the neccessary measures on your end (the business). You can setuo 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": 4499,
        "reference": "MZQ3X2DE2SMX",
        "customer_email": "john.doe@gmail.com",
        "currency": "USD",
        "payment_method_type": "CARD",
        "redirect_url": "https://mystore.com.pa/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)