# Webhooks

Source: https://docs.pitchpointsolutions.com/developer_guides/webhooks/index/

**Beta**

## 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](https://docs.pitchpointsolutions.com/api/workflow/get_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:

```text
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](https://docs.pitchpointsolutions.com/api/webhooks/events#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.

> **API Reference:** [Obtaining An Access Token](https://docs.pitchpointsolutions.com/developer_guides/authentication/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

- [Getting Started](https://docs.pitchpointsolutions.com/developer_guides/webhooks/getting-started) — register an endpoint and receive a first verified delivery.
- [Verifying Signatures](https://docs.pitchpointsolutions.com/developer_guides/webhooks/verification) — prove a delivery came from PPS, in Java, Python or Node.
- [Receiving Deliveries](https://docs.pitchpointsolutions.com/developer_guides/webhooks/receiving) — the envelope, idempotency, what to respond, and retries.
- [Troubleshooting](https://docs.pitchpointsolutions.com/developer_guides/webhooks/troubleshooting) — it isn't arriving: inspect, diagnose, replay.
- [Webhooks API Reference](https://docs.pitchpointsolutions.com/api/webhooks/index) — every operation, every property, and the complete error vocabulary.