Sandbox certification

Certification is self-service: when you can run this script end to end in the sandbox, your integration is ready. Every step uses your sk_test_ key against https://api.sandbox.rostergiving.com.

0. Register a webhook endpoint

curl -X POST https://api.sandbox.rostergiving.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $SK_TEST" \
  -H "Idempotency-Key: setup-webhook-1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/roster/webhooks",
    "event_types": ["enrollment.created", "enrollment.activated"]
  }'

Store the secret from the response — it is shown only once. Then prove your receiver works (signature check included) with a test delivery:

curl -X POST "https://api.sandbox.rostergiving.com/v1/webhook_endpoints/$ENDPOINT_ID/test" \
  -H "Authorization: Bearer $SK_TEST" \
  -H "Idempotency-Key: test-webhook-1"

{"delivered": true} means your endpoint answered 2xx to a signed envelope.

1. Import your churches

curl -X POST https://api.sandbox.rostergiving.com/v1/churches/import \
  -H "Authorization: Bearer $SK_TEST" \
  -H "Idempotency-Key: import-batch-1" \
  -H "Content-Type: application/json" \
  -d '{"churches": [{"name": "First Baptist"}, {"name": "Grace Chapel"}]}'

The response has a result per item — an invalid row never fails the batch. Keep the returned church ids.

2. Open a donor session

curl -X POST https://api.sandbox.rostergiving.com/v1/donor_sessions \
  -H "Authorization: Bearer $SK_TEST" \
  -H "Idempotency-Key: donor-jane-1" \
  -H "Content-Type: application/json" \
  -d '{
    "church_id": "'$CHURCH_ID'",
    "donor_phone": "+15005550006",
    "mode": "pct",
    "value": 10,
    "redirect_url": "https://your-app.example.com/thanks"
  }'

The 201 response carries a url — the hosted flow. It is returned once and expires in 30 minutes. redirect_url must be https on an origin from your allowlist (configured with us during onboarding).

3. Complete the flow as a seed donor

Open the url in a browser and walk through it: phone verification (the sandbox simulates SMS), consents, payroll connection. When the enrollment is created you will receive enrollment.created on your webhook.

4. Activate the enrollment

In production, activation happens when the payroll provider confirms the direct-deposit switch. In the sandbox, you trigger that confirmation yourself — through the same pipeline production uses:

curl -X POST https://api.sandbox.rostergiving.com/sandbox/simulate/payroll-connected \
  -H "Authorization: Bearer $SK_TEST" \
  -H "Idempotency-Key: activate-1" \
  -H "Content-Type: application/json" \
  -d '{"enrollment_id": "'$ENROLLMENT_ID'", "church_id": "'$CHURCH_ID'"}'

enrollment.activated arriving on your webhook is the certification moment — it is the signal your production integration will live on.

5. Cross-check on the event feed

curl "https://api.sandbox.rostergiving.com/v1/events?type=enrollment.activated" \
  -H "Authorization: Bearer $SK_TEST"

The same event, by pull. Store next_cursor and poll with since_cursor for reconciliation — the feed is the source of truth when a webhook is missed.

Checklist

Webhook endpoint registered, test delivery delivered: true
Churches imported with per-item results handled
Donor session created; hosted flow completed by a seed donor
enrollment.created and enrollment.activated received and deduplicated by event_id
Feed polling with cursor persistence in place

Introduction

Webhooks