> For the complete documentation index, see [llms.txt](https://developers.gallantreecapital.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gallantreecapital.com/webhooks/subscribe.md). # Subscribe to events Webhooks let you react to changes in Gallantree data without polling. Register a subscription, and the platform will `POST` a signed event to your endpoint whenever one of the events you're interested in occurs. ## Prerequisites * A registered [developer app](/getting-started/register-an-app.md) with the `webhooks:manage` scope. * An **HTTPS endpoint** you control. HTTP is rejected — the platform will not deliver over an insecure transport. * A shared **signing secret** you can retrieve from the portal after creating the subscription. You'll use it to verify signatures on every delivery. ## Events you can subscribe to | Event | When it fires | | ------------------------------ | -------------------------------------------------------------------------------------- | | `loan.created` | A new loan is added to a lender's portfolio | | `loan.updated` | Fields on an existing loan change | | `loan.status_changed` | A loan moves between states (e.g. active → discharged) | | `loan.assessment_completed` | A credit assessment for a loan finishes | | `document.generated` | A document (loan doc, credit memo, statement) is generated and available for retrieval | | `collateral.valuation_updated` | A collateral valuation is updated | | `organisation.kyb_completed` | KYB verification for an organisation finishes | | `coverage_test.breach` | A capital-program coverage test breaches its threshold | New events are added over time; design your handler to log-and-ignore unknown `X-Gallantree-Event` values. ## Create a subscription From the portal, open your app → **Webhooks** → **New subscription**. Provide: * **URL** — the HTTPS endpoint that will receive deliveries. * **Events** — one or more event types (comma-separated in the API; multi-select in the portal). * **(Optional) Encryption fingerprint** — for the Enterprise tier, you can supply a public key so the platform encrypts payloads before signing them. Skip this for standard use. Each app can have up to **10 active subscriptions**. ## The delivery payload Every delivery is a `POST` with `Content-Type: application/json`. The body is a compact JSON object with three top-level fields: ```json { "event": "loan.created", "timestamp": "2026-08-15T04:32:11.482Z", "data": { "id": "65f3a8b1d5c9e4f2a1b3c4d5", "reference": "SBX-000123", "lenderId": "65a0000000000000000000f0", "principal": { "amount": 250000, "currency": "AUD" }, "createdAt": "2026-08-15T04:32:11.100Z" } } ``` * **`event`** is the event type — the same value you'll find in the `X-Gallantree-Event` header. * **`timestamp`** is when the platform prepared the delivery (ISO 8601, UTC). Also mirrored in `X-Gallantree-Timestamp`. See [Verify signatures](/webhooks/verify-signature.md) for how to use it to reject replays. * **`data`** is the event-specific payload. Its shape depends on the event; the reference documents each one. Headers on every delivery: ``` Content-Type: application/json X-Gallantree-Signature: X-Gallantree-Event: loan.created X-Gallantree-Delivery: X-Gallantree-Timestamp: 2026-08-15T04:32:11.482Z ``` Test deliveries (from the portal's **Send test** button) additionally carry `X-Gallantree-Test: true`. ## Responding to a delivery * **Return `2xx` quickly.** Any `2xx` status marks the delivery as successful. Anything else marks it failed and triggers the retry schedule (see [Delivery and retries](/webhooks/delivery-and-retries.md)). * **Respond within 30 seconds.** The platform gives up on a delivery after 30 seconds and treats it as failed. Do your actual work asynchronously — enqueue the payload and `200` immediately. * **Deduplicate on `X-Gallantree-Delivery`.** The platform may retry a delivery, and your receiver may occasionally receive a duplicate; use the delivery id to no-op the second one. ## Runnable example — subscription creation Use the portal for real subscriptions; the raw HTTP shape is shown here for completeness: ```bash curl -sS -X POST https://developers.gallantreecapital.com/api/v1/webhooks \ -H "x-api-key: $GALLANTREE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "url": "https://myapp.example.com/webhooks/gallantree", "events": ["loan.created", "loan.status_changed"] }' ``` The response includes a `secret` field — the signing secret. Copy it into your secret store and use it in [Verify signatures](/webhooks/verify-signature.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.gallantreecapital.com/webhooks/subscribe.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.