API Destinations

  • Updated

What are API Destinations?

API Destinations enables Voxie to connect to any other marketing and data tools, once the connection is set, it can be leveraged in Event-Based Rules in order to assemble the Data Payload needed by the Target platform.

This feature is also commonly known as Webhooks and allows your application to pass information or “call” other applications, tools, and servers via HTTP request. Webhooks send information about an event that has occurred (e.g. an Message Sent, a new Contact subscribed, etc).

API Destinations List

Found in: Settings > Integrations > API Destinations

Each API destination will count with a Name, entered by the user that will be referenced when used in an Event-Based Rule definition.

The details of the header Attributes are going to be explained in the next section.

New API Destination

Once the user clicks on “New API Destination”, the following configurations need to take place:

  • Name: The Name of the API Destination that will be referenced in the List as well as in Event-Based Rules Actions

  • Endpoint: URL destination, usually found in the Developers Portal of the target application or server

    • URL Variables: In case each Event will need to point to a different URL, although the use case is the same, the variable can be added between curly brackets {}

      e.g. The use case is to update Contacts, and these contacts are identified in the URL with their email, then:

      https://api.coolapp.com/contacts/v1/createOrUpdate/email/{contact_email}/

      Where the contact_email is a variable that will be used in the Automations Actions

  • Method: specific instructions that clients send to a web server to indicate the desired action on a particular resource. They are essential for enabling efficient and secure communication between clients and servers. Each HTTP request method has a distinct meaning and purpose, and they are categorized based on their impact on the server's state.

    • POST: The POST method is used to submit data to a specified resource, often resulting in a change in state on the server. POST requests are commonly used to submit form data, create new resources, or update existing ones.
    • PUT: The PUT method is used to replace the entire content of a specified resource with the data sent in the request body. It is considered idempotent, meaning that repeating the same PUT request multiple times produces the same result. PUT requests are typically used to update entire resources.
    • PATCH: The PATCH method is used to apply partial modifications to a specified resource. It is similar to PUT, but it only updates specific parts of the resource rather than replacing the entire content. PATCH requests are more efficient for updating specific fields or attributes of a resource.
    • DELETE: The DELETE method is used to remove a specified resource from the server. It is considered a safe method because it does not alter the state of any existing resources. DELETE requests are typically used to delete web pages, files, or other data stored on the server.

  • API Auth: Select or Create the set of credentials available for this API Destination, the ones define in API Endpoints Auth

API Destinations in Event-Based Rules Actions

In Event-Based Rules Actions, after the Trigger and Matching conditions are defined, one of the possible actions is Invoke API Destination and needs to be configured as follows:

Select API Destination: ability to select existing API Destination or Add new one

URL Variables: Variables part of the URL defined in the API Destination can be called as:

  • Team Variables
    • team.id
    • team.name
    • team.custom_attributes.store_name
  • Contact Variables
    • contact.id
    • contact.phone
    • contact.first_name
    • contact.last_name
    • contact.entry_point
    • contact.tags
    • contact.custom_attributes.key1
    • contact.custom_attributes.key2
    • contact.subscriptions.transactional
    • contact.subscriptions.marketing

Payload:

The Payload Editor is based on JMSPath, which enables the HTTP call to be configured and tailored following the specifications of the Endpoint App requirements.

💡 Be aware, each application you are going to connect to, have their own data schema and therefore requirements, it is highly recommended to count with a developers page or professional savvy of the application.

 

API Deliveries for Troubleshooting

API Destinations set up may be challenging, that’s why it presents a set of visuzalisation screens that ease the troubleshooting of initial set up.

You can access by clicking into API Deliveries, that lists in a log fashion, all the delivery attempts this API destination configuration triggered, when, and what was the source.

If you click on each Log or Record Attempt Details, it will take you to the debugging screen, in which you’ll have all the necessary information to understand the current behavior of this API Destination

Delivery ID: Internal unique identifier of the Job

Metadata: HTTP Method, Header and URL used, this is key to understand if in case of the usage of variables in the API destination, if it is being rendered correctly

Request Payload: This section is key, since it shows back how the Request Body was rendered with the data we intended to send to the target Endpoint, if it matches the Data Schema needed to accept the request.

API Auth: The method and set of credentials used in order to authenticate with the API Destination Endpoint.

Automation: Which was the automation Event-Based Rules that triggered this event.

Attempts: Log of the different Attempts this single job try to perform

  • Status: A summary of the HTTP response code
      • Success: This happens when the end server responds with an HTTP status code between 200 and 299
      • Redirection Error: This happens when the end server responds with an HTTP status code between 300 and 399
        • We do not follow redirects for security and performance reasons
      • Too Many Requests Error: This happens when the end server responds with an HTTP status code of 429
      • Client Error: This happens when the end server responds with an HTTP status code between 400 and 499 other than 429
      • Server Error: This happens when the end server responds with an HTTP status code greater than or equal to 500
      • Network Error: This happens if there is some kind of network issue that prevented us from sending the request (this could be a DNS resolution issue, failed TLS handshake, etc)
      • Timeout Error: This happens if the target server took too long to handle the request and complete sending a response
      • Auth Config Error: This happens if the auth config is not found (unusually this would happen if someone deleted an auth config that was still in use, maybe for a retrying attempt)
      • Internal Error: This happens if our delivery system crashes - users should contact Voxie support if they are seeing this frequently
  • Completed: When this was performed
  • Duration: How long did it took to be performed.
  • Attempt ID: Internal Job Identifier.
  • Response: Another Key aspect of the API destinations Log, depending on the verbosity of the Target Endpoint, this response can detail why, in case it wasn’t succeed, it didn’t went through.