DEVELOPER GUIDE

View as Markdown

Beta

Webhooks

Overview

A webhook is an HTTP POST PPS sends to an endpoint you host, carrying one event as JSON. Instead of polling Read a Workflow for changes, you register an HTTPS endpoint once and receive a request each time a subscribed event occurs.

You manage webhooks through the Webhooks API, under this base URL:

https://api.pointservices.com/riskinsight-services-ws/resources

How it fits together

Endpoint — the HTTPS URL you register, together with the topics it accepts and how its deliveries are signed. It has an id, 4711 in these docs, which every other call takes.

Org unit — a node in your organization’s org unit tree, and the structure an endpoint belongs to. On the wire it is a string like OU41502, and org unit GUIDs are globally unique. Your PPS account manager supplies yours. You cannot discover or invent it, and you need it before your first register call.

Destination domain — the domain your endpoint URL points at. PPS must authorize it before deliveries are sent there; ask your account manager.

Subscription grant — an entitlement written by PPS and never by you. It routes one product’s events, for named topics, from the org unit that produces them to one destination org unit, matched exactly. An endpoint receives its own org unit’s events as soon as it declares the product and topic, with no grant. You need a grant only for events produced in another org unit, and that includes your own parent or sibling org units: grants do not inherit up or down the tree.

Event — one business occurrence, with a stable eventId. There are eight topics in two families. The workflow topics, workflow.pending, workflow.updated and workflow.failed, follow a run through processing. The finding topics, finding.result_updated, finding.reviewed, finding.note_updated, finding.attachment_updated and finding.attachment_removed, say which finding changed and how. See Event Topics.

Delivery — one attempt to POST one event to one endpoint. It is a row you can inspect and replay.

Three conditions for receiving

An endpoint’s receiving property is true only when all three hold: the endpoint is enabled, its circuit is CLOSED, and it has declared at least one product and topic in acceptedEventTypes. Read receiving rather than enabled, which is true for plenty of endpoints that are receiving nothing.

receiving is one answer for the whole endpoint. It does not say that a particular product or topic will arrive: an endpoint receives only what it declared, and events produced in another org unit also need a grant, which receiving does not check.

When receiving is false, notReceivingReason names the one condition that failed, and therefore who fixes it.

notReceivingReason What it means Who fixes it
NOT_DECLARED The endpoint declares no accepted event types, so no event can ever match it. You, by adding products and topics to acceptedEventTypes.
DISABLED The endpoint is switched off (enabled: false). PPS does not switch an endpoint off after failures; it opens the circuit instead. You, by re-enabling it.
CIRCUIT_OPEN The circuit breaker opened after repeated delivery failures or a 410 Gone. It closes on its own once your endpoint responds successfully.
NO_GRANT No live grant covers the endpoint’s declared selectors. An endpoint that has declared anything receives its own org unit’s events without a grant, so this value is not expected in practice. Handle it anyway. PPS. Contact your PPS account manager.

Exactly one cause is reported even when several hold at once, in the order of the table: declaring comes first, because an endpoint that declares nothing is reached by no route, then the endpoint’s own switch, then its circuit.

Authenticating to the API

Every request to the Webhooks API carries a bearer token in the standard Authorization header, written as Authorization: Bearer <token>. That is the mechanism this API supports, and it is checked before the request body is read.

You obtain a token by signing in with the credentials PPS issues you. An access token expires one hour after it is issued, so your integration has to refresh it. Refreshing is not enough on its own: the refresh token has its own, shorter lifetime, and once it expires a refresh is rejected. An unattended integration must be able to sign in again on its own when that happens, rather than assuming a refresh token lasts indefinitely.

Obtaining An Access Token — how to sign in, and how to refresh before the hour is up.

Receiving webhooks is the other direction and needs no token of yours: your server verifies the signature PPS sends.

Where to go next

Table of contents

Copyright © Pitchpoint Solutions. All rights reserved.