Introduction Concepts App Registration Making API Test Calls Authentication OData Search Events and Webhooks Specifications Profiles API Agencies API Licenses API Accounts API Plans API Policies API Events API Carriers API Content API

Events and Webhooks

The Event/Webhook Relationship

An event is an instance of data changing in Zywave. A webhook responds to events by sending a POST request to a user-specified URI. The body of the request will contain information about the event, such as the time the event took place, the type of record that changed, and the ID of the record. A full list of the events that webhooks can listen to, as well as a summary of the data delivered in the POST requests, is available in the Events API.

A webhook can only listen to events on data that you own, and only to one kind of event. For instance, if you have a webhook that listens to account change events, it can only respond to changes to account records for your agency.

Verifying Webhook URIs

Whenever you create a webhook or change the URI that a webhook sends messages to, the events API must verify the URI. The API starts by searching verified domains in your organization for the domain of the webhook URI; if the API finds a verified domain that matches the domain of the URI, the URI is verified. If not, the API sends a GET request to the URI with a random string in a challenge URI query parameter. If the response to the request contains the value of the challenge parameter, the URI is verified.

If both verification attempts fail, the URI is not verified. The POST or PUT that triggered the verification will fail and any existing webhook data will be unchanged.

Webhook Startup

Once the URI is verified, the webhook needs to subscribe to its corresponding event using Zywave-internal listening mechanisms. Although this is done automatically, the time required to complete the subscription process may vary. You can monitor the webhook's readiness status by viewing the webhook using the Events API.

Webhook Behavior Details

Once the webhook is subscribed to its event, it can begin sending POST requests whenever the event fires.

Note: There may be a delay of up to five minutes for webhooks triggered by activity in amc.zywave.com.

When a webhook's HTTP request fails, the webhook will try the request again a short time later. Each time the request fails after the first retry, the webhook will increase the time that it waits before retrying. The webhook will stop retrying after twelve failed request attempts.

Because sending data to a remote URI entails certain risks, Zywave has taken the following steps to keep your data safe.

  • We never send sensitive data to the URI specified in a webhook. For example, when a record changes, we don't send a copy of the record. Instead, we send the record ID so that you can get your view the record with an authenticated API call. A complete list of data delivered with each type of event can be found by using the Events API to query the event definition specifications.
  • Instead of using raw JSON in the message body, we send event data in a signed JWT. By verifying the JWT signature, you can be sure that the message came from the Zywave system. The event data itself can then be retrieved as a JSON BLOB from the zywave_webhook_data claim.