Receive webhooks from AuthPI for all events

Webhooks are like the secret sauce for making your app super responsive to what’s happening in AuthPI. Set them up, and you’ll get instant updates on user activities and subscriptions, letting you automate tasks and keep everything in sync effortlessly. This guide is here to help you set up a webhook endpoint on your dashboard or via the API, break down the data format, and share tips on verifying signatures, handling retries, and responding to events. Let’s get started!

Create a new webhook endpoint

On your dashboard

Go to the webhooks section of your dashboard and click on the Create Webhook button. You will be asked to provide a name for your webhook and the URL where you want to receive the events.

Using the API

You can also create a new webhook using the API. You can use the following endpoint to create a new webhook:

curl -X POST https://api.authpi.com/v1/accounts/{account_id}/webhooks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "My webhook",
        "url": "https://my-webhook-endpoint.com"
    }'

The documentation of this endpoint is available here.

Data in request

The data sent by our webhooks are following the CloudEvents specifications for maximum interoperability. Most of the times, you will only be interested in the data field of the event, which contains the actual payload of the event.

{
  id: "1234-1234-1234-1234",
  specversion: "1.0",
  source: "com.authpi.webhooks/v1/<webhook_id>",
  type: "event",
  datacontenttype: "application/json",
  time: "2024-01-01T03:21:36Z",
  data: {
    id: "9876-9876-9876-9876",
    type: "user.created",
    trace: "abc123",
    source: "com.authpi/v1",
    subject: {
      user_id: "user-1",
    },
    data: { ... }
  }
}

Handling Retries

In case of a failure in processing a webhook event, AuthPI will retry sending the event several times. Ensure your endpoint can handle duplicate events and implements idempotency.

Responding to Webhooks

Your webhook endpoint must return a 200 HTTP status code to acknowledge successful receipt of the event. If AuthPI receives any other status code, it will consider the delivery as failed and will retry the event delivery.

Common Use Cases

user.created event

When a new user is created in AuthPI, a user.created event is sent. You can use this event to trigger actions in your application, such as provisioning resources or updating your user database. With user.updated, you can keep your user database in sync with AuthPI.