Register a webhook endpoint

​

The signing secret (whsec_...) is returned only in the creation response. Store it; every delivery is signed with it (see the Webhooks section). Idempotent replays return the endpoint without the secret. Up to 3 active endpoints per partner: registering a fourth returns 400 — delete one you no longer use first.

Headers

  • Idempotency-Key
    Type: string
    min length:  
    1
    max length:  
    255
    required

    Required on every POST, before any effect: 1–255 visible ASCII characters, no spaces. The key belongs to the first body sent with it on this operation for 30 days from the moment that request arrives, including while that request is running and after a 5xx or a timeout. On an operation that creates a resource (POST /v1/churches, POST /v1/churches/import, POST /v1/church_consents, POST /v1/donor_sessions, POST /v1/manage_sessions, POST /v1/refunds and POST /v1/webhook_endpoints), a key whose request succeeded keeps its body for as long as the resource it created exists. A creation replayed with the same key and body returns the original resource with 200 and changes nothing; a 4xx releases the key.

Body·

required
application/json
  • event_types
    Type: 1…enum
    required

    Kinds of notices this address is subscribed to receive.

  • url
    Type: string
    max length:  
    2000    Format: uri
    required

    Must be https on the default port, to a public hostname. IP literals, credentials in the URL and reserved suffixes (.internal, .local) are rejected at registration, and so are hostnames that resolve to private address space. A hostname that doesn't resolve yet is accepted. At most 3 active endpoints per partner.

Responses

  • application/json
  • application/json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
Request Example for post/v1/webhook_endpoints
curl https://api.sandbox.rostergiving.com/v1/webhook_endpoints \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "url": "",
  "event_types": [
    "partner_session.created"
  ]
}'

{
  "id": "we_9d8c7b6a5f4e",
  "url": "https://example.com",
  "event_types": [
    "partner_session.created"
  ],
  "status": "active",
  "created_at": "2026-10-22T14:55:08.127Z",
  "secret": "string"
}

Idempotent replay — same endpoint, without secret.

Previous
Webhook endpoints
Next
List active webhook endpoints