Alfa

Webhooks

Set your webhook endpoint

PUT/v1/integration/webhook-endpoint

Sets the HTTPS URL this key receives the company's events at, and enables it. The first time, the answer includes the signing `secret`, shown only once. A platform key sets one endpoint for each client company, named by `Alfa-Company-Id`. A URL that resolves to a private or internal address is 422 `invalid_webhook_url`. Requires an API key with the `webhooks:manage` scope.

Requires an Alfa API key as a bearer token. How API keys work

Headers

  • Alfa-Company-Idstring

    The Company ID of the company to act for. Required with a platform key, and that company must have authorized your platform; a company key acts for its own company and can leave it out.

Request body

  • urlstringrequired

    An HTTPS URL on the public internet.

    at most 2000 characters · format uri

Response body

  • keyIdintegerrequired

    The API key the endpoint belongs to.

  • companyIdstringrequired

    The company whose events it receives.

  • urlstringrequired

    Where events are sent.

  • status"enabled" | "disabled"required

    `disabled` after three days of failed deliveries, or once removed. Setting the URL again enables it.

  • failingSincestring | nullrequired

    When the current run of failed deliveries began; null while deliveries succeed.

  • disabledAtstring | nullrequired

    When the endpoint was disabled.

  • createdAtstringrequired

    When the endpoint was created.

  • updatedAtstringrequired

    When the endpoint last changed.

  • secretstring

    The signing secret, returned only when it is created or rotated. Store it; it is never shown again.

Responses

  • 200Success.
  • 400The request is malformed: invalid JSON, an unexpected body or an unknown query parameter. Problem details
  • 401The bearer token is missing, expired or invalid. Problem details
  • 403The caller may not perform this operation, or has no active organisation. Problem details
  • 404The resource does not exist or is not visible to the caller. Problem details
  • 422The request failed validation; `errors` lists each invalid field. Problem details
  • 429Too many requests, or the AI service is busy. Retry after a short wait. Problem details
  • 500An unexpected error. Quote the `correlationId` to support. Problem details