Skip to main content

Webhooks & Sales Notifications

Webhooks:#

Use the webhooks to receive notification on events occurring in the Virtual Library.

As of 2019-11-08 the supported events are the following:

  • A sale of a single publication.
  • A sale of a prepaid plan.
  • Monthly payment of a recurring plan.

A webhook is a POST request, whose body contains a parameter called “token”. This token is a JWT (JSON Web Token) that contains all the event information. The JWT are signed using the standard, with the algorithm HS256, and allow who uses to be certain that the webhook is coming from publica.la.

To use the webhooks system you need to provide an URL and create a key. The URL is the endpoint to whick we will send the webhook and the key will be used to sign the webhooks. Both the URL and the key can be managed on the /dashboard/settings#integrations inside your virtual library.

The only requirement is to receive a 2xx (200, 201, etc) notification after the webhook is sent. This way our system can understand the notification was received successfully. In case the response code is other the system will take the notification has failed and will make 2 new attempts with a 3 hours delay each.

Details of the implementation:#

The body request of a webhook is a JSON with the following format:

{
"json": {
"token_type": "jwt",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
}

The JWT on every webhook share some characteristics:

  • A value with the property “iss” to the string “farfalla”
  • Are valid for 5 minutes once created.
  • They have as value of the property "sub" the type of event, for example "sale".
  • They have as value of the property "aud" the slug of the library, for example "naciondigital".

Useful links:

Sales Notifications:#

Sales Notifications can be transmitted through the Webhook system or by email.

As of 2019-11-08 the supported events are the following:

  • A sale of a single publication.
  • A sale of a prepaid plan.
  • Monthly payment of a recurring subscription.

The system notifies each sale 20 minutes after these are confirmed. Offline payments (Rapipago, Easy Payment, etc.) can take up to 72 hours to be reported as "confirmed" by the provider. For recurring subscriptions, system will send notification each month when invoice paid successfully The payload of a Sale Notification is the same for both email and JWT mediums, it has the following format:

{
"event_type": "sale",
"event_subtype": "single",
"uuid": "0d2d4b9a-1660-4418-8f51-96840b780190",
"job_id": "1231412",
"queued_at": 1554388826,
"environment": "live",
"payload": {
"user": {
"external_id": null,
"uuid": "3909be20-ff61-4e14-8c8b-9fd334a9ecf6",
"email": "admin@rd3.com.ar",
"name": "Charles N Salinas",
"national_id": "123456",
"billing_information": {
"address_line_1": "Stoney Lane",
"address_line_2": "Farmers Branch",
"city": "Texas",
"state": "Texas",
"country": "EEUU",
"postal_code": "2285",
"other_information": null
}
},
"payment_details": {
"gateway": "stripe",
"method": "card"
},
"issue": {
"external_id": "11241353",
"name": "EjemploPublicala",
"description": null,
"publication_date": "2018-07-16",
"prices": [
{
"currency_id": "ARS",
"amount": 4500
},
{
"currency_id": "USD",
"amount": 500
}
],
"file_type": "pdf",
"reader_url": "https:\/\/farfalla.test\/reader\/ejemplopublicala",
"is_free_until": "2019-03-29",
"require_login_when_free": false,
"is_free": true
},
"user_plan": {
"uuid": "699ed863-0445-4570-9f6b-4fa0fd350052",
"plan_type": "single",
"currency_id": "ARS",
"amount": 2250,
"gateway": "mercadopago",
"own_gateway" : 0
},
"coupon": {
"code": "TESTCOUPONCOD111",
"amount": 50,
"uses": 2,
"use_limit": 10,
"valid_to": "2019-05-01"
}
}
}

Fields details:

  • type: string, this data is mandatory and will always be present.
  • subtype: string, this data is mandatory and will always be present.
  • uuid: string, the unique identifier of the notification.
  • job_id: job identifier,
  • queued_at: job execution timestamp,
  • payload: It is an object that contains
    • user: It is an object that contains
      • uuid: string, unique identifier unrepeatable.
      • email: string or null
      • external_id: string or null, will be present in the event that the user comes from some integration.
      • name: string or null, will be present in the event that the user completes his name in the billing information of his profile.
      • billing_address: string or null, will be present in the event that the user adds his address in the billing information of his profile.
        caution

        This parameter is deprecated and is going to be removed the 1st of January of 2021

      • extra_billing_information: string or null, will be present in the event that the user completes extra data in the billing information of his profile
        caution

        This parameter is deprecated and is going to be removed the 1st of January of 2021

      • national_id: integer, the name of the user.
      • address_line_1: string or null, the address of the user.
      • address_line_2: string or null, the address complementary of the user.
      • city: string or null, the city of the user.
      • state: string or null, the state of the user.
      • country: string or null, the country of the user.
      • postal_code: string or null, the postal code of the user.
      • other_information: string or null, another billing information of the user.
    • issue: It is an object that contains
      • external_id: string or null, usually the ISBN of the publication.
      • name: string
      • description: string or null
      • publication_date: string, in "2013-09-13" format.
      • prices: array of objects that contain currency type and amount in cents
        • currency_id: string, always present (ARS, USD, COP, PEN, MXN, EUR).
        • amount: integer in cents (500, would be 5 Argentine pesos).
      • file_type: string, is always present (pdf or epub).
      • reader_url: string, URL to the publication in the reader.
      • is_free_until: string or null, in "2013-09-13" format. This data is used to indicate to what date a publication is free.
      • require_login_when_free: true or false, indicates if it is necessary to log in to the system to be able to read the free publication.
      • is_free: true or false, indicates if the publication is free and freely accessible.
    • user_plan: It is an object that contains
      • uuid: string, unique identifier unrepeatable.
      • plan_type: string, always present.
      • currency_id: string, always present (ARS, USD, COP, PEN, MXN, EUR).
      • amount: integer in cents (500, would be 5 Argentine pesos).
      • gateway: string, means of payment used for sale (Mercadopago, Paypal, Payu or Stripe).
      • own_gateway: boolean, Indicate payment occur via tenant owned gateway or not.
    • coupon: it is an optional object that contains
      • code: string, code generated for the coupon always present,
      • amount: integer, percentage of discount applied, always present,
      • uses: integer, number of times the coupon has been used, always present,
      • use_limit: integer, maximum number of times that the coupon can be used, optional,
      • valid_to: string, maximum coupon use date, optional