Skip to main content

Webhooks

Webhooks push real-time notifications to your systems when things happen in your loyalty program — so you don't have to poll. You register an HTTPS endpoint, choose which event types it should receive, and Weave delivers a signed POST for each matching event.

Creating an endpoint​

The quickest path is the dashboard: Developers → Webhooks, where you can add an endpoint, pick its event types, and see delivery history.

You can also create one through the API with POST /webhooks/endpoints:

curl -X POST https://api.loomloyalty.com/webhooks/endpoints \
  -H "Authorization: Bearer $LOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/weave",
    "endpointType": "CLIENT",
    "filterTypes": ["<event type>", "<event type>"],
    "description": "Order service"
  }'
FieldRequiredDescription
urlyesThe HTTPS destination that receives deliveries.
endpointTypeyesCLIENT for a customer-configured endpoint.
filterTypesyesThe event types this endpoint should receive.
descriptionnoA label to help you recognize the endpoint later.

Handling a delivery​

Each delivery is a POST to your url with a message describing the event:

{
  "messageId": "…",
  "eventType": "…",
  "eventId": "…",
  "payload": {}
}
  • eventType tells you what happened; payload carries the details.
  • eventId is the caller-supplied id for correlation and idempotency — deduplicate on it so a redelivered message is processed once.
  • Respond quickly with a 2xx status to acknowledge receipt. Weave retries deliveries that fail or time out, so do heavy work asynchronously.

Verifying signatures​

Each endpoint has a signing secret you can retrieve (GET /webhooks/endpoints/{id}/secret) and rotate (POST /webhooks/endpoints/{id}/secret/rotate). Use it to verify that a delivery genuinely came from Weave before trusting it, and rotate it if it's ever exposed.

Retries and debugging​

  • Test messages — send a sample delivery to confirm an endpoint is wired up (/webhooks/endpoints/{endpointId}/test-messages).
  • Attempts — inspect each delivery attempt and its response to debug failures.
  • Recoveries — replay messages to an endpoint after an outage.

Connectors​

To deliver into a downstream tool without writing a receiver, apply a connector (connectorKind) such as ZAPIER, MAKE, SEGMENT, or INNGEST, or connect Slack from the dashboard, which installs a transformation that formats events as Slack messages. Use CUSTOM for raw, untransformed delivery.

Next Steps​