Webhook

Webhooks are a way to send frontier activity events to an external service. Frontier supports sending events to a webhook URL when a user performs an action in the system. This allows you to integrate Frontier with other services and automate workflows.

Configuration

Start by registering a webhook endpoint via the Frontier API. By sending a POST request to the v1beta1/admin/webhooks endpoint with the following payload:

{
  "body": {
    "description": "My Webhook",
    "url": "https://example.com/webhook",
    "subscribed_events": [],
    "headers": {
      "Authorization": "Bearer sample-token",
      "Content-Type": "application/json"
    }
  }
}

It will create a new webhook with the specified URL and headers. The subscribed_events field is optional and can be used to specify which events you want to receive. If you don't specify any events, you will receive all events.

Events

Frontier sends the following events to the webhook URL:

app.user.created
app.user.updated
app.user.deleted
app.user.listed
app.serviceuser.created
app.serviceuser.deleted

app.group.created
app.group.updated
app.group.deleted

app.role.created
app.role.updated
app.role.deleted

app.permission.created
app.permission.updated
app.permission.deleted
app.permission.checked

app.billing.entitlement.checked

app.policy.created
app.policy.deleted

app.organization.created
app.organization.updated
app.organization.deleted
app.organization.member.created
app.organization.member.deleted

app.project.created
app.project.updated
app.project.deleted

app.resource.created
app.resource.updated
app.resource.deleted

Security

To ensure that the webhook is secure, when the create endpoint is called, Frontier will return a secret key. This key will be used to sign the payload sent to the webhook URL. The secret key is generated by Frontier and is unique to each webhook.

When Frontier sends an event to the webhook URL, it will include a X-Signature header with the signature of the payload. The signature is generated by hashing the payload with the secret key using the HMAC-SHA256 algorithm. The webhook service should verify the signature by hashing the payload with the secret key and comparing it with the X-Signature header.

Once the payload hmac is verified, the webhook service should verify the created_at timestamp in the payload. The timestamp should be within 5 minutes of the current time to prevent replay attacks.

{
  "id": "123",
  "created_at": "2021-10-01T12:00:00Z",
  "action": "app.user.created",
  "data": {
    "user_id": "123",
    "name": "John Doe",
  }
}

If you are using Go, an existing function can be used to do the verification

Retry Policy

Frontier will retry sending the event to the webhook URL if it fails to connect or the webhook service returns an error. The retry policy is exponential backoff with a maximum of 3 retries.