Waymark Plugin — Webhooks

You can configure webhook endpoints to be notified about events that happen to accounts tied to your partner account. Webhooks are used for asynchronous events like the completion of a video render.

What are webhooks?

Webhooks are HTTP endpoints that you create on your own servers to receive notifications when something happens with your partner account. You can determine what you want the URL to be to receive Waymark webhook events and we will call it with a POST request containing a Waymark event object in JSON form.

When to use webhooks

Webhooks should be used when you need to guarantee that you receive notice of events whether the account in question is currently active in a browser application or not. For example, video rendering can take several minutes depending on the complexity of the video template. If your user edits a video, completes it, and then closes the browser before Waymark has finished the rendering of the new video, you will need a webhook to receive the notification that the render has been completed.

Receiving a webhook event

Webhooks should return a 2XX HTTP status code as soon as the event is successfully received. If Waymark attempts a webhook request and the response code is anything other than a 2XX status (including redirects or other 3XX status codes), we will attempt the repeat the request after a short timeout. After repeated failures we will mark the event as failed and stop trying to send it to your webhook endpoint.

If your webhook endpoint fails repeatedly, Waymark may disable it after a period of time.

Event handling

Duplicates

On occasion, an event may be sent to a webhook more than once. Please structure your handling code such that repeated events will be ignored. This can be accomplished by logging the webhook event ID and not processing events that have already been seen.

Ordering

Waymark does not guarantee that webhooks will arrive in any particular order.

Security

Making sure that only Waymark can call your webhook endpoints is important to protect your users' information.

Webhook verification

Waymark can sign each webhook event using your API webhook secret to allow you to confirm that it is a valid request. Signing of webhook requests is optional but recommended.

If you wish to have webhook events signed, please contact your Waymark account representative.

HTTPS

Using HTTPS on your webhook endpoints will prevent others from snooping the webhook event data.

Events

Each event payload consists of a header section that contains information about the event itself and the account that generated the event, and a data section that contains the actual event data.

Unsigned Events

Unsigned events are posted as a JSON string and will have a content type of application/json:

{
   "header": {<the header section data object>},
   "data": {<the individual event data as described for each event>}
}
{
  "eventID": "1234-ABCD-1234-ABCD",
  "eventType": "video.rendered",
  "eventTimestamp": "2019-08-08T16:22:38.924635Z",
  "accountID": "1234-ABCD-1234-ABCD",
  "externalID": "<partner provided ID>"
}

Event types

Video Completed

Event type: video.completed

This webhook event will be sent whenever a video is completed (purchased) by an account. The data will consist of a video object.

{
  "id": "1234-ABCD-1234-ABCD",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "isPurchased": true,
  "name": "A Video About Cars",
  "templateID": "1234-ABCD-1234-ABCD",
  "renders": []
}

While the SDK will also send this event, the webhook should be considered more reliable as it does not require the user to be actively using a Waymark UI session to receive it.

Video Rendered

Event type: video.rendered

This webhook event will be sent whenever a video completed by an account has finished rendering. The data will consist of a video object.

It is worth noting that Waymark will render a new video in both web and TV / streaming quality formats. You may receive multiple render events because each of these renders may complete at different times. When this happens both renders will be present, each with a potentially different status.

{
  "id": "1234-ABCD-1234-ABCD",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "isPurchased": true,
  "name": "A Video About Cars",
  "templateID": "1234-ABCD-1234-ABCD",
  "renders": [
    {
      "renderedAt": "2019-08-08T16:22:38.924635Z",
      "format": "broadcast_quality",
      "url": "https://x.y.z/12345.mov",
      "status": "succeeded"
    },
    {
      "renderedAt": "2019-08-08T16:22:38.924635Z",
      "format": "email",
      "url": "https://x.y.z/12345.mp4",
      "status": "in_progress"
    }
  ]
}

Status values for video renders are:

While the SDK will also send this event, the webhook should be considered more reliable as it does not require the user to be actively using a Waymark UI session to receive it.

Account Created

Event type: account.created

This webhook event will be sent whenever a new account is created for a user associated with your partner account. The data will consist of an account object.

{
  "id": "1234-ABCD-1234-ABCD",
  "firstName": "Mabel",
  "lastName": "Tierney",
  "emailAddress": "mtierney@example.com",
  "companyName": "Tierney Auto, Inc.",
  "phone": "248-555-1212",
  "city": "Dearborn",
  "state": "MI"
}

Generally this event will only be of interest to partners that enable Waymark account creation via the Waymark UI.

Signed Events

Signed events will be posted as a JSON Web Token (JWT) that is signed using your Waymark-provided secret key and will have a content type of application/jwt.

The header will contain the algorithm and the type, typically "HS256" and "JWT", respectively:

{
  "alg": "HS256",
  "type": "JWT"
}

The payload will contain the webhook event and will have this structure:

    {
        "jti": "unique ID for this JWT",
        "iss": "waymark.com",
        "iat": issued-at timestamp,
        "exp": expiration timestamp,
        "https://waymark.com/webhook/event": {
          // This will be the unsigned event as described above
        }
    }