Webhook for claimed invitations

User flow

When an invitation that a VASP created has been claimed, the VASP will receive a webhook to inform them that the invitation has been claimed.

Handling the webhook

The webhook is an HTTP POST request made to the address the VASP provided in their API Config Settings.

See the full documentation on configuring and handling webhooks here.

It is expected that the response to this webhook is fast (a few seconds at most), and is a 200 HTTP response code. If the response status is different, Lightspark will consider the webhook failed and will retry with an exponential backoff.

The HTTP body of the webhook is a JSON representation of an invitation, including:

the invitee_uma field, which should be used to inform the inviter that their invitee has created their UMA
the incentives_status, which should be checked to forward incentives to the inviter or not.

Handling payments after the webhook

If your invitation included an amountToSend, your platform is responsible for sending the payment to the invitee after receiving the UMA_INVITATION_CLAIMED webhook. The webhook payload will include the invitation details, including the amount and currency to display to the user.

Recommended flow:

When you receive the webhook, check if the invitation has an amountToSend field.
If present, initiate the payment to the invitee's UMA address using your platform's payment logic.
Handle any errors or failures in the payment process. If the payment fails, the invitee will not receive the amount, and you may want to notify the inviter or take other action.
Log the payment status for auditing and support purposes.

Note: The actual transfer of funds is not handled by Lightspark. Your platform must implement the logic to send the payment after the invitation is claimed.

Example of server-side handling

import express from "express";
import {
  WebhookEvent,
  WebhookEventType,
  WEBHOOKS_SIGNATURE_HEADER,
  verifyAndParseWebhook
} from "@lightsparkdev/lightspark-sdk";

const app = express();

app.post("/webhook", (req, res) => {
  const event = await verifyAndParseWebhook(
    req.body,
    req.headers[WEBHOOKS_SIGNATURE_HEADER],
    ({}).LIGHTSPARK_WEBHOOK_SIGNING_KEY
  );

  if (event.event_type === WebhookEventType.UMA_INVITATION_CLAIMED) {
    const invitationId = event.entity_id;
    // You can now fetch the details of the invitation using the SDK:
    const invitation = await lightsparkClient.executeRawQuery(
      UmaInvitation.getUmaInvitationQuery(invitationId)
    );
  }

  res.send("OK!");
});

app.listen(3000, () => {
  console.log("Server listening on port 3000");
});