Webhook Set up

Webhooks overview

Point uses webhooks to push real-time notifications to your application when an event happens. These notifications are sent using a POST request with the information as a JSON payload in the request body.

Steps to receive webhooks

You can follow these steps to start receiving event notifications:

Check the events reference guide to understand more about the events you want to subscribe to.
Create a webhook endpoint as an HTTP endpoint (URL) on your server.
Set up your endpoint as a webhook in Point's dashboard.
Handle requests from Point by parsing each event object and returning 2xx response status codes.
Secure your webhook using the webhook signature header flow.

Use the Event Types reference guide to identify the Point events and their event objects your webhook endpoint needs to parse.

Step 2: Create a webhook endpoint

Set up an HTTP endpoint on your server that can accept unauthenticated webhook requests with a POST method. For example:

POST https://thisismyapi.com/v1/point-webhook

Step 3: Set up your endpoint as a webhook in Point's dashboard

You should enter Point's dashboard with your account and set up your newly created endpoint to a new webhook attaching it to the events you want to monitor.

Step 4: Handle requests from Point

Point sends events to your webhook endpoint as part of a POST request with a JSON payload. Your endpoint must be ready to receive the events and their respective payloads.

Check event objects

Each event is structured as an object with eventType, userId, userExternalId, dataSource from which this new data originated, the clientId for your specific app and the event payload nested in the payload attribute. This payload attribute is an array with one to many payload objects from the event. Your endpoint must check the eventType and parse the payload of each event. For example this event for event type workout.created:

{
  "userId":"point|123",
  "userExternalId":"123",
  "eventType":"workout.created",
  "dataSource":"apple_health",
  "clientId":"2LCcsx1YYvWZ0MX-Eyss51321CaLu0csvLp9",
  "payload": [{ <event type related data> }, ...]
}

Return a 2xx response

Your endpoint must quickly return a successful status code (2xx) prior to any backend logic that could cause a timeout (30 seconds). For example, you must return a 200 response before updating your database.

Built-in retries

Point's webhooks have built-in retries for all non 2xx response status codes (3xx, 4xx, or 5xx). If Point doesn’t receive a 2xx response status code for an event in all the retries, we mark the event as failed and stop trying to send it to your endpoint. After multiple failed events, we email you about the misconfigured endpoint and automatically disable it. Once your endpoint is back to work, all you need to do is to reactivate your webhook in Point's dashboard.

Step 5: Securing your webhooks

Use webhook signatures to verify that Point generated the webhook request and that it didn’t come from a server acting like Point.

Email Us

Webhook Set up