Handling Prism API Webhook Events

Prism Hosted API can push webhook events right to your server! But how do you receive them? Here are the basic implementation steps for using Prism Webhooks in your API.

Getting Started ✅

First, we need a single server endpoint url from you that will receive all webhook events. Please share the address for receiving webhooks with one of the Prism developers if you haven’t already. Once that is complete, it’s time to set up webhooks!

Webhook Overview

The webhook is a POST request to a single endpoint provided by a partner that contains an event type and a payload.

If a webhook event fails (i.e. the endpoint returns a status not in the 200s or the connection fails), the Prism server will attempt to re-send the event three times—immediately upon failure, then again after 5 and then 30 seconds. After that it will stop.

Webhook Payload

The webhook body looks like this, with an eventType specifying the type of message being sent, and the payload being all the data associated with that type of event.

{
  eventType: WebhookEventType;
  payload: ScanPayload | FutureMePayload;
};

Webhook Event Types

Listed in the table are possible events you can expect from our API.

Scan Processing Webhook Events

Here’s what a webhook event looks like for scans. This snippet is formatted in Typescript, but the same field types can be created and applied in any language.

{
  eventType: WebhookEventType;
  payload: {
	scanId: string;
	userId: string;
	userToken: string;
	state: ScanStatus;
  };
};

See "Webhook Event Types" and the "Scan Statuses" section for more information on those specific fields. The rest of the webhook fields are straightforward. The scanId and userId are generated internally by our database system, and the userToken is the token we received from you for a user to be used for verification. (Note: the userId is to help with debugging in the event that something goes wrong, but otherwise does not need to be saved.)

Scan Statuses

Listed in the table are possible scan statuses you can expect from our API.