Introduction

Welcome to our API reference documentation! The Wreno API offers a robust, RESTful programming interface for securely accessing your Wreno account data.

Authentication

Acquiring an API Secret Key:

To get started, you will need to obtain an API Secret Key from the Wreno support team. This key is a confidential piece of information that serves as your initial authentication mechanism. The secret key should be kept secure and not shared publicly. Reach out to your support team to request the key.

Including the Secret Key in Requests:

With the API Secret Key in hand, include it in the Authorization header of every request you make to the API. The header should be formatted as follows: 

Authorization: Bearer YOUR_API_SECRET_KEY

Replace YOUR_API_SECRET_KEY with the actual secret key provided by Wreno.

Making API Requests:

With the Secret Key in place, you can now access the API's endpoints as described in the OpenAPI specification. Each request is validated by the API server to ensure proper authorization for accessing resources.

This approach allows you to use the same secret key for both initial authentication and ongoing API access. Make sure to securely manage and protect the key to prevent unauthorized access to your API. If you have any issues or questions, contact your API provider's support team for assistance.

Webhooks

Use incoming webhooks to get real-time updates

When building Wreno integrations, you might want your applications to receive events as they occur in your Wreno account, so that your backend systems can execute actions accordingly.

To enable webhook events, our support team will register your webhook endpoint. Wreno can then push real-time event data to your application's webhook endpoint when events happen. Wreno uses HTTPS to send webhook events to your app as a JSON payload that includes an Event object.

Webhook Endpoints

To use webhooks you will need to establish an endpoint that our Wreno services can make a request to whenever the data you're interested in changes.

Your endpoint should meet the following requirements:

  • Support HTTPS protocol
  • Be publicly accessible
  • Handle POST requests with JSON payloads sent as raw data and a Content-Type of application/json.

It's crucial that your endpoint responds quickly when receiving webhook callbacks. If Wreno doesn't receive a response within 10 seconds, the callback is considered unsuccessful. As a best practice, your endpoint should return a response before executing any complex logic to ensure a response within the 10-second duration. Any HTTP response code from your endpoint other than a 2XX is also considered an unsuccessful request. Wreno will retry unsuccessful events at specific intervals:

  1. After 10 seconds
  2. After 30 seconds
  3. After 1 minute
  4. After 10 minutes
  5. After 1 hour

If a callback for an event remains unsuccessful after five attempts, Wreno will stop further attempts to send the event message.

Signature Checks

We strongly recommend validating webhook event signatures in your application to ensure that requests originate from Wreno and not from malicious actors attempting to impersonate or tamper with event messages. This validation enhances the overall security and data integrity of your application.

All webhook callback requests include a signature and a timestamp in the HTTP headers.

HTTP Header Description
wreno-timestamp A UNIX timestamp indicating when the message was sent.
wreno-signature A computed signature generated using the secret key, which can be used to verify the request's authenticity. The secret key is generated when setting up the webhook subscription with Wreno's support team.

The signature is a combination of the timestamp and the event message hashed using a secret key. The secret key is generated when creating webhook subscriptions. It's vital to securely store this key, just like any other credentials. Follow these steps to verify the request using the secret key, event message, and HTTP header values:

  1. Concatenate the value of the wreno-timestamp header with the event body, separating them with a period. The event body should have all newlines removed and no spaces after colons between property names and values.
  2. Hash the concatenated string using the HMACSHA256 algorithm, using the webhook secret key as the algorithm key.
  3. Convert the resulting hash bytes to a base64 string.
  4. Compare the base64 string to the value of the wreno-signature header. If the values match with a case-sensitive comparison, the message is validated as originating from Wreno.

Example Code:

Webhook Setup

  1. Identify which events you want to monitor.
  2. Create a webhook endpoint function to receive event data via POST requests.
  3. Register your endpoint with Wreno's support team.

1. Identify Events

Use the Wreno API reference to determine the events you wish to monitor. Look for events labeled with the "WEBHOOK" tag.

2. Create Webhook Endpoint

Establish an HTTPS endpoint function capable of accepting webhook requests with a POST method. Ensure it:

  • Handles POST requests with a JSON payload, including an event object.
  • Returns a successful status code (2xx) before executing any potentially time-consuming logic.

3. Register Your Endpoint

Share your endpoint's URL with Wreno's support team. They will assist in registering your endpoint URL with Wreno and conduct integration testing to ensure smooth operation.

Event Object