Get started
Webhooks

Webhook endpoints

Webhook endpoints

An endpoint is an https URL of yours that Mountaya sends webhook events to. An organization holds 2 of them unless its agreement says otherwise, 6 at most. Its owners and admins manage them.

In the Mountaya app

  1. Open Organization → Webhooks, then the Endpoints tab.
  2. Select Add endpoint. Enter the URL, then pick the event types it is sent.
  3. Copy the signing secret it shows, and store it on your server as MOUNTAYA_WEBHOOK_SECRET. An owner or an admin can reveal it again on the endpoint's page.

The same page lists every event and every delivery, and shows how reliably each endpoint receives them.

Through the API

Use a key that carries the management scope, and a session token naming an owner or admin. Your organization's id is in the Mountaya app's address, after /organizations/.

export MOUNTAYA_SESSION_TOKEN=$(curl -s -X POST https://api.mountaya.com/v1/sessions \
  -H "X-API-Key: $MOUNTAYA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"publishable_key\": \"$MOUNTAYA_MANAGEMENT_KEY\", \"user_id\": \"7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1\"}" \
  | jq -r .data.token)

Create an endpoint

curl -s -X POST "https://api.mountaya.com/v1/organizations/$MOUNTAYA_ORGANIZATION_ID/webhook-endpoints" \
  -H "X-API-Key: $MOUNTAYA_MANAGEMENT_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/mountaya", "description": "Membership sync", "enabled_events": ["organization.member.*", "collection.deleted"]}' \
  | jq '.data | {id, status, enabled_events, secret}'
Response
{
  "id": "e4b7a1d9-5c26-4f83-a0e1-7d2c9b6f3a85",
  "status": "enabled",
  "enabled_events": ["organization.member.*", "collection.deleted"],
  "secret": "whsk_8f3c2a71b845d0e4c7a6b3f180d92e5a17c4e9b0d36f2a58e1c7b4093d6a2f15"
}

Choose event types

enabled_events lists what an endpoint is sent. Each entry takes one of three forms.

EntrySends
collection.deletedThat type alone
collection.*Every type of the collection family, and no other family
*Every type, those added later included

A family stops at its own name. collection.* sends collection.created, never collection.itinerary.added: add collection.itinerary.* for that. Event types lists every family.

Disable and enable

Set status to disabled to stop deliveries, and back to enabled to resume them from the next event.

curl -s -X PATCH "https://api.mountaya.com/v1/organizations/$MOUNTAYA_ORGANIZATION_ID/webhook-endpoints/$MOUNTAYA_WEBHOOK_ENDPOINT_ID" \
  -H "X-API-Key: $MOUNTAYA_MANAGEMENT_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status": "disabled"}' \
  | jq '.data | {status, disabled_reason}'
Response
{
  "status": "disabled",
  "disabled_reason": "requested"
}

Events recorded while an endpoint is disabled are not sent when you enable it again. Before you enable it, read its failing_since, then redeliver from that moment if you need them.

Delete an endpoint

Deleting an endpoint stops its deliveries and frees its place under your agreement's limit. Its past deliveries stay readable, and you can still filter them by its id.

curl -s -X DELETE "https://api.mountaya.com/v1/organizations/$MOUNTAYA_ORGANIZATION_ID/webhook-endpoints/$MOUNTAYA_WEBHOOK_ENDPOINT_ID" \
  -H "X-API-Key: $MOUNTAYA_MANAGEMENT_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Who can manage endpoints

  • In the Mountaya app: the organization's owners and admins.
  • Through the API: a key carrying management, with a session token naming an owner or admin.

Revealing or rotating a secret is done in the Mountaya app only.

Next steps

Last updated