fingerlydocs
fingerly.io Log inDashboard
API reference

Webhook endpoints

Create, update, pause and delete webhook endpoints, rotate their signing secrets, send test events and redeliveries, and read delivery attempts.

Register the endpoints Fingerly sends webhooks to. Admin and developer management keys can do all of this. An organization can have up to 10 endpoints.

Path parameter

  • organization_idstringrequired
    Your organization, from Describe the key. A path naming any other organization answers 404.

List endpoints

GET/api/v1/management/organizations/{organization_id}/webhooks Management key

Response

  • endpointsWebhookEndpoint[]
    Every endpoint, newest first.
    12 child fields
    • idstring
      The endpoint's ID.
    • urlstring
      Where deliveries are sent.
    • descriptionstring
      Your description.
    • environmentstring
      live for production traffic, test for staging and development.
    • eventsstring[]
      The event types the endpoint receives.
    • statusstring
      active, paused or failing.
    • secret_last4string
      The last four characters of the signing secret.
    • previous_secret_expires_atstring
      During a rotation, when the previous secret stops signing.
    • delivered_24hinteger
      Deliveries that succeeded in the last 24 hours.
    • failed_24hinteger
      Deliveries that failed in the last 24 hours.
    • last_delivery_atstring
      When the endpoint last received a delivery.
    • created_atstring
      When the endpoint was created.

Create an endpoint

POST/api/v1/management/organizations/{organization_id}/webhooks Management key

Body

  • urlstringrequired
    An https:// URL that resolves to a public address. Redirects are not followed.
  • environmentstringrequired
    live or test.
  • eventsstring[]required
    Event types, such as identification.completed. billing.status_changed needs live.
  • descriptionstringrequired
    To tell endpoints apart. May be empty.

Answers 201 with endpoint and secret, the signing secret, shown once. A request past the limit of 10 endpoints answers 409 with webhook_limit.

Update an endpoint

PATCH/api/v1/management/organizations/{organization_id}/webhooks/{webhook_id} Management key

Body

  • urlstring
    A new URL.
  • descriptionstring
    A new description.
  • environmentstring
    live or test.
  • eventsstring[]
    The complete new list of event types.
  • pausedboolean
    true pauses the endpoint; false resumes it.

Send only the fields to change. Answers with the endpoint.

Delete an endpoint

DELETE/api/v1/management/organizations/{organization_id}/webhooks/{webhook_id} Management key

Removes the endpoint and answers 204. Deliveries stop at once.

Rotate the signing secret

POST/api/v1/management/organizations/{organization_id}/webhooks/{webhook_id}/rotate-secret Management key

Body

  • previous_secret_valid_hoursintegerDefault 24
    How long the previous secret keeps signing deliveries, from 0 to 168.

Answers with endpoint and the new secret, shown once. See rotate a secret.

Send a test event

POST/api/v1/management/organizations/{organization_id}/webhooks/{webhook_id}/test Management key

Queues one signed webhook.test delivery and answers 202 with its event_id. A test or redelivery already queued for the endpoint answers 409 with webhook_busy.

Redeliver an event

POST/api/v1/management/organizations/{organization_id}/webhooks/{webhook_id}/redeliver Management key

Body

  • event_idstringrequired
    The ID of an event this endpoint received in the last 30 days.

Queues one more delivery of the event, with the same id, and answers 202.

List delivery attempts

GET/api/v1/management/organizations/{organization_id}/webhook-deliveries Management key

Query parameters

  • environmentstringDefault 'all'
    live, test or all.
  • limitintegerDefault 50
    Attempts per page.
  • cursorstring
    The next_cursor of the previous page.

Response

  • deliveriesDelivery[]
    Attempts from the last 30 days, newest first: id, endpoint_id, endpoint_url, event_id, event, environment, status (delivered, retrying or failed), response_code, duration_ms, attempt, error and occurred_at.
  • next_cursorstring
    Pass it as cursor for the next page. Omitted on the last page.

Last updated