PingPlotter Cloud Manual

Webhooks

PingPlotter Webhooks will give you the ability to do things like notify you when an Agent is online/offline, or when an Agent's connection degrades.

Need help?

Shoot us an email: support@pingman.com. We'll connect you with one of our Customer Success Reps who can provide guidance on implementation and best practices.

Create a new Webhook

To create a Webhook go to Manage --> Webhooks --> Create Webhook.

Create a new webhook.

Give this Webhook a descriptive name so that you can easily remember what it's being used for.

Select an option for when you should be notified:

  1. When Agent connection status changes - Sent when an Agent's connection status changes for more than 60 seconds (e.g. Online to Offline).
  2. When quality changes - sent when the Quality Value of an Agent's Target(s) changes for more than 60 seconds (e.g. good to poor).
  3. When Agent is created - sent when any Agent is created either using the ad-hoc method or via the Agent Template.
  4. When Agent is deleted - sent when any Agent is deleted.

Enter your Webhook URL, any headers, and the method. Use the Test Call button to test your configuration. Once everything is all set, hit Create Webhook.

Custom Fields as Headers

Any of your configured custom fields can be passed as a header. For example, if you have a field called "Manager", you can send the Agent's correspoding "Manager" value by adding a header with the key: Manager and value: {{CustomFields.Manager}} .

Variables

Any of the variables in this list can be passed as URL parameters or headers, e.g. https://my.webhoook.com/?Agent= {{AgentName}} .

Webhook Event Variables
Agent Connection Status Changed {{AgentUniqueId}} , {{AgentName}} , {{IsOnline}} , {{CustomFields.CustomFieldName}}
Agent Created or Deleted {{AgentUniqueId}} , {{AgentName}} , {{CustomFields.CustomFieldName}}
Quality Changed {{AgentUniqueId}} , {{AgentName}} , {{IsOnline}} , {{CustomFields.CustomFieldName}} , {{OnWifi}} , {{LastMessageTime}} , {{OnVPN}}

Use Cases

Here are some examples of how you could use Webhooks:

  1. Connection Quality Notifications - send your Agent's a notification when their connection is unsuitable for taking calls.
  2. Offline Agent Notifications - get notified if your server loses Internet connection.
  3. New Agent Notifications - create a ticket when your customer accesses their online portal and installs an Agent.
Codeless Implementation

Send your Webhook to a service like Zapier or Power Automate to connect with compatible apps or start a Workflow without needing to write any code.

Debouncing, Retries, and Other Notes

  • Debounce Settings - Webhooks are debounced for 60 seconds for every event. If another event of the same type for the same source occurs within that minute, only the latest event will be notified on (with the same 60 second wait), the previous event will be ignored.
  • Retries - All Webhook failures will be retried up to 5 total times. Each retry attempt will be 30 seconds apart from one failure to another. Results of the final webhook attempt can be found in the Webhooks logs (Manage --> Webhooks --> Logs). Users can manually retry individual webhooks from the logs table (there are no automatic retries associated with the manual retry).
  • Authentication - authentication can be handled by adding the necessary headers or by passing the credentials as a URL parameter. It is recommended to follow the authentication practices provided by your Webhook endpoint.
  • Webhook Body - currently the body of the Webhook is fixed. Anything not included in the body of the Webhook may be passed as a header or URL parameter using a variable.
  • Rate Limits - there are currently no rate limits for PingPlotter Webhooks. Failures due to endpoint rate limits can be found in the Webhook logs.