Webhooks

Polling for state changes is fine if you only have a few users. Once you’re at scale, you want push. We support six event types you can subscribe to. Each one fires the moment the underlying state changes — usually within 500 ms of the trigger event. You confirm receipt with a 2xx HTTP response. We retry with exponential backoff on failure.

The events

Event	Triggered by
`consent.granted`	User grants you a new consent.
`consent.revoked`	User revokes a consent.
`consent.expired`	Consent reached its `expiresAt` without renewal.
`consent.renewed`	User extended an existing consent before it expired.
`standing.tier_changed`	A user with an active consent changed standing tier (e.g., Emerging → Trusted).
`repayment.settled`	A repayment for a loan you disbursed landed in the user’s wallet (via direct debit or manual).
`repayment.failed`	A repayment direct-debit attempt failed (insufficient funds, bank error).
`disbursement.delivered`	A disbursement you initiated successfully reached the user’s wallet or bank.
`disbursement.failed`	A disbursement failed (typically a name-mismatch or bank rejection).

Subscribing

POST /partner/v1/webhooks:

curl -X POST https://api.guild.com.ng/partner/v1/webhooks \
  -H "Authorization: Bearer gld_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourbank.com.ng/webhooks/guild",
    "events": [
      "consent.granted",
      "consent.revoked",
      "standing.tier_changed",
      "repayment.settled",
      "repayment.failed"
    ],
    "description": "Production partner webhook"
  }'

Response:

{
  "id": "whk_01HMFB...",
  "url": "https://yourbank.com.ng/webhooks/guild",
  "events": ["consent.granted", "consent.revoked", "standing.tier_changed", "repayment.settled", "repayment.failed"],
  "secret": "whsec_01HMFB...",
  "status": "ACTIVE",
  "createdAt": "2026-08-14T10:58:21Z"
}

Save the secret — it’s shown exactly once. This is what you’ll use to verify every incoming webhook’s signature.

The payload shape

Every webhook delivery is a POST with this shape:

{
  "id": "evt_01HMFB...",
  "type": "standing.tier_changed",
  "createdAt": "2026-08-14T11:02:33Z",
  "data": {
    "userId": "usr_01HMFB...",
    "consentId": "cnst_01HMFC...",
    "previousTier": "Emerging",
    "newTier": "Trusted",
    "previousScore": 547,
    "newScore": 553
  },
  "partnerId": "prt_01HK...",
  "apiVersion": "v1"
}

Headers include the signature:

X-Guild-Signature: t=1755168153,v1=5d9c8...
X-Guild-Webhook-Id: whk_01HMFB...
X-Guild-Event-Id: evt_01HMFB...
Content-Type: application/json
User-Agent: Guild/1.0

Verifying the signature

Same shape as Stripe and similar. The signature header has two fields:

t — the Unix timestamp when we signed.
v1 — the HMAC-SHA256 of {timestamp}.{raw_body} using your webhook secret.

Verification:

Extract t and v1 from the header

Split on , and parse the key=value pairs.

Check the timestamp

Reject if t is more than 5 minutes off from your server’s time (replay protection).

Compute the expected signature

HMAC_SHA256(secret, "{t}." + raw_body) and hex-encode.

Compare with v1 in constant time

Use a constant-time comparison (hmac.compare_digest in Python, crypto.timingSafeEqual in Node, hash_equals in PHP, CryptographicOperations.FixedTimeEquals in C#, MessageDigest.isEqual in Java). Do not use string equality.

Process the event only if signature matches

Otherwise return 401 and log the event for investigation.

Reference implementations

Copy-paste-ready verifiers in five languages (JavaScript, Python, PHP, C#, Java) live on Security → Webhook verification → Verifying in your language. Each one handles signature parsing, timestamp drift checking, HMAC computation, and constant-time comparison. Use those rather than implementing from scratch. Reference implementations in Python, Node.js, and Go on the Partner Portal.

Idempotency

Webhooks can be redelivered. Treat them as at-least-once. Every event has an id (e.g., evt_01HMFB...). Store the ID after successful processing. On the next delivery, check the store — if you’ve seen the ID, return 200 immediately without reprocessing. A simple Redis or Postgres events_processed(event_id PRIMARY KEY, received_at TIMESTAMP) table works for almost everyone. TTL the rows at 30 days.

Looking up an event

You can look up any event your organisation has been delivered, by ID.

GET /partner/v1/events/{eventId}

This endpoint is open to any authenticated key — no scope required. You can only see events delivered to your own webhooks (the lookup is automatically scoped to your partnerId).

curl https://api.guild.com.ng/partner/v1/events/evt_01HMFB... \
  -H "Authorization: Bearer gpk_live_..."

Response 200

string

Event ULID prefixed evt_.

string

Event type, e.g. DISBURSEMENT_DELIVERED.

object

The exact JSON body we POSTed to your endpoint(s).

string

ISO-8601 timestamp the event was raised.

array

One entry per webhook subscription that received this event. Each delivery has the same shape as GET /webhooks/:id/deliveries: id, webhookId, status (PENDING|DELIVERED|FAILED|GIVEN_UP), attempt, lastStatusCode, firstAttemptAt, nextAttemptAt, deliveredAt, givenUpAt, createdAt, lastResponseBody.

{
  "id": "evt_01HMFB...",
  "type": "DISBURSEMENT_DELIVERED",
  "payload": {
    "id": "evt_01HMFB...",
    "type": "DISBURSEMENT_DELIVERED",
    "createdAt": "2026-08-14T11:02:33Z",
    "data": { "disbursementId": "dis_01HMFD...", "status": "DELIVERED" },
    "partnerId": "prt_01HK...",
    "apiVersion": "v1"
  },
  "createdAt": "2026-08-14T11:02:33Z",
  "deliveries": [
    {
      "id": "whd_01HMFB...",
      "webhookId": "whk_01HMFB...",
      "status": "DELIVERED",
      "attempt": 1,
      "lastStatusCode": 200,
      "deliveredAt": "2026-08-14T11:02:34Z",
      "createdAt": "2026-08-14T11:02:33Z"
    }
  ]
}

Error cases

HTTP	Code	When
404	`invalid_input`	The event ID isn’t recognised, or the matching event wasn’t delivered to any of your webhooks.

Use this to reconcile audit-log discrepancies, debug a missed delivery, or correlate a signature you logged with the event we generated.

Delivery and retries

We deliver from a queue. Order is not guaranteed — events for the same user may arrive out of order. Use the createdAt field on the event payload if order matters for your processing. On a non-2xx response (or no response within 30 seconds), we retry with exponential backoff:

Attempt	Delay since last
1	30 seconds
2	5 minutes
3	30 minutes
4	2 hours
5	12 hours
6	24 hours
7+	24 hours, max 14 days total

After 14 days of failed delivery, we mark the event as undeliverable and stop retrying. You can replay it from the Partner Portal dashboard later. We don’t count 200, 201, 202, 204 as success — any 2xx works. We treat 410 Gone as “permanently disabled — don’t retry.”

Filtering

You can configure multiple webhook subscriptions, each filtered to a subset of events. Common patterns:

One subscription for consent events (consent.*) routed to your customer-success system.
One subscription for standing changes routed to your underwriting service.
One subscription for repayment events routed to your loan-servicing system.

Different subscriptions can have different secrets, allowing the receiving teams to operate independently.

Listing and managing subscriptions

curl https://api.guild.com.ng/partner/v1/webhooks \
  -H "Authorization: Bearer gld_live_..."

Response is an array of subscriptions. Each has stats (delivered count, failed count, average latency over the last 24h). To update an existing subscription (e.g., add or remove events):

curl -X PATCH https://api.guild.com.ng/partner/v1/webhooks/whk_01HMFB... \
  -H "Authorization: Bearer gld_live_..." \
  -H "Content-Type: application/json" \
  -d '{"events": ["consent.granted", "consent.revoked"]}'

To delete:

curl -X DELETE https://api.guild.com.ng/partner/v1/webhooks/whk_01HMFB... \
  -H "Authorization: Bearer gld_live_..."

Deletion is immediate.

Local development

Three good ways to receive webhooks without standing up a backend:

webhook.site — instant temporary URL that captures and displays every request it receives, including our headers and the signed body. Best for a quick smoke test.
smee.io — forwards public webhook traffic to a local URL on your machine.
ngrok — public tunnel to your localhost service.

Testing from the Partner Portal

Inside the Partner Portal at partners.guild.com.ng/webhooks, every active subscription has a Send test action. It fires a synthetic delivery through the same queue and signing pipeline as real events — the only difference is a test: true flag in the envelope so your handler can filter it out if it wants to. The test delivery picks an event your subscription is registered for, generates a representative sample payload, signs it with your webhook secret, and posts it to your URL. It then appears in the deliveries panel with timestamps, response code, and retry status, exactly like a real event. You can also replay any prior delivery from the Portal — useful for debugging a handler crash without waiting for the next live trigger.

Webhook security checklist

The standard list. We won’t enforce all of these but you’ll thank yourself for them later.

✅ Verify signatures on every request. Reject if the signature fails.
✅ Reject events older than 5 minutes (replay protection).
✅ Check idempotency using event_id.
✅ Return 2xx quickly. Don’t do heavy processing inline — push to a queue.
✅ Run handlers in a separate worker if the work is heavy.
✅ Log failed deliveries with the request body for debugging.
✅ Keep the webhook URL stable. If you must change it, update the subscription before changing your DNS.
✅ Monitor delivery success rate. We surface it in the dashboard; alert if it drops below 99%.

Failure modes you’ll see

What happens	What it means	What to do
Webhook delivers but your handler returns 500	Your service is having a bad day	We retry. Fix your service.
Webhook delivers but you can’t process the event yet	Event arrived before the prerequisite (e.g., `repayment.settled` for a loan you don’t know about)	Return 200, drop the event. We’ll see it again if needed. Or queue locally and reprocess later.
Webhook signature verification fails	Either your secret is wrong (rotation issue) or we sent something unexpected (security incident)	Log everything, return 401. Open a ticket.
Multiple events for the same underlying state	Race condition or retry	Your idempotency check filters this.
No webhook arriving when you expected one	Your subscription might have been disabled. Or you’re looking at the wrong event type.	Check `/partner/v1/webhooks` for status. Check the Portal dashboard for delivery history.

Rate limits

Throughput numbers for the API.

Snapshots

The data that lives behind every consent.

Get Started

For Job Seekers

For Traders

For Employers

For Partners

Channels

Standing & the Ledger

Architecture

Security & Trust

The events

Subscribing

The payload shape

Verifying the signature

Reference implementations

Idempotency

Looking up an event

Response 200

Error cases

Delivery and retries

Filtering

Listing and managing subscriptions

Local development

Testing from the Partner Portal

Webhook security checklist

Failure modes you’ll see

Next

Rate limits

Snapshots

​The events

​Subscribing

​The payload shape

​Verifying the signature

​Reference implementations

​Idempotency

​Looking up an event

​Response 200

​Error cases

​Delivery and retries

​Filtering

​Listing and managing subscriptions

​Local development

​Testing from the Partner Portal

​Webhook security checklist

​Failure modes you’ll see

​Next

Rate limits

Snapshots

The events

Subscribing

The payload shape

Verifying the signature

Reference implementations

Idempotency

Looking up an event

Response 200

Error cases

Delivery and retries

Filtering

Listing and managing subscriptions

Local development

Testing from the Partner Portal

Webhook security checklist

Failure modes you’ll see

Next