Set up webhooks

You need an API key that can make changes and a public HTTPS address on your server. Replace the example addresses and key below with your own.

A webhook is a POST request Viffy sends to that address. Your server checks the signature, saves the event, and responds to confirm receipt.

1. 1

   Read the original request body

   Keep the raw bytes before parsing JSON. Use the signature verification example to check each delivery with your webhook secret.
2. 2

   Save the event before confirming receipt

   After verification, store the event or add it to a durable queue, then return a 2xx response within ten seconds. Process it afterward.
3. 3

   Handle repeat deliveries and samples

   Use the event’s id to avoid applying the same event twice. Acknowledge events with sample: true but leave them out of business updates.

This example subscribes to new redemptions and both kinds of correction. It keeps your integration informed when a redemption is excluded or restored.

curl -X POST https://YOUR-VIFFY-ADDRESS/api/partner/v1/webhooks \
  -H "Authorization: Bearer vfy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://YOUR-PUBLIC-ADDRESS/viffy/events",
    "eventTypes": [
      "redemption.recorded",
      "redemption.excluded",
      "redemption.restored"
    ]
  }'

The response contains webhook.id and secret. Save the ID and configure your server to verify deliveries using the full secret.

For other events and every response field, see the webhook reference.

Replace WEBHOOK-ID with the ID returned when you registered the address.

curl -X POST https://YOUR-VIFFY-ADDRESS/api/partner/v1/webhooks/WEBHOOK-ID/test \
  -H "Authorization: Bearer vfy_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "redemption.recorded" }'

The response confirms that a sample is queued. It does not confirm that your server received it.

Read GET /webhooks/{id} and check recentDeliveries for the sample’s event ID. A populated deliveredAt confirms that your server acknowledged it.

You can also inspect recent deliveries under Settings → API access in Viffy. If the sample fails, use webhook troubleshooting.

• For an exclusion or restoration, fetch the current redemption with GET /redemptions/{id} before updating your copy. Deliveries can arrive out of order.
• Keep a saved position in the event log so you can recover missed events.
• Compare your saved redemption totals with creator counts before crediting creators.