Skip to main content

Using Relays

This page will walk you through the steps of using a Webhook Relay to receive real time updates on singular donations.

Steps to Receive Relayed Donations​

1. Create a Relay in your Developer Dashboard​

Relays are an advanced method of receiving donations and require that you first configure the following resources in your Developer Dashboard:

Once you have created a Webhook Relay, you will find the webhook_relay_id that is used to make API requests in your Developer Dashboard.

a screenshot of the webhook relay id

2. Create a Relay Key with the Tiltify API​

A Relay Key is a single use client visible key that initiates the donation tracking. A Relay Key may optionally have some custom fields to facilitate tracking of the donation. When we send donation updates to your Webhook Endpoint, these custom fields will also be available in the payload.

  • id (optional string) - You can pass an ID of up to 255 characters that can be used for reconciliation later. If one is not provided, we will generate a UUID for you. Note that the id must be unique across the entire Relay.

  • metadata (optional string) - You can pass any metadata of up to 4096 characters to help identify the purpose of the donation.

caution

Metadata is stored and returned as a string, do not put any personally identifying information in your custom metadata.

Tiltify API Request to create a Relay Key​

In order to use the endpoint to create a Relay Key, you must use an Application Access Token with the webhooks:write scope. For more information see the API Reference

curl -X POST https://v5api.tiltify.com/api/private/webhook_relays/8e615ce4-9246-42d3-b3b2-b3fba2b55d2a/webhook_relay_keys \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer ab6a592346444dea97170837e104d8a5ab6a592346444dea97170837e104d8a5' \
   -d '{"id":"internal_2OyjGiv8ODkZqhvjmA0vmsY49JT","metadata":"eyJjdXN0b20iOiJtZXRhZGF0YSJ9"}'

If everything goes well, you should receive a successful response that looks like:

{
  "data": %{
    "client_key": "dc6e53fd4dce7d9f9509618367f8aa67eba8e14dda94c9d9d2e418318784fcbd",
    "donation": null,
    "id": "internal_2OyjGiv8ODkZqhvjmA0vmsY49JT",
    "inserted_at": "2023-05-12T00:41:51.412985Z",
    "metadata": "eyJjdXN0b20iOiJtZXRhZGF0YSJ9",
    "updated_at": "2023-05-12T00:41:51.412985Z",
    "webhook_relay_id": "8e615ce4-9246-42d3-b3b2-b3fba2b55d2a"
  }
}

3. Redirect the User's Browser using the client_key​

Take the client_key returned from your successful API request, and use it to redirect the user to a Tiltify donation form. You will pass this client_key as a url query parameter.

Query Parameter Format​

Template example

https://donate.tiltify.com/@username/campaign-slug?relay=<client_key>

Example with a client_key

https://donate.tiltify.com/@username/campaign-slug?relay=dc6e53fd4dce7d9f9509618367f8aa67eba8e14dda94c9d9d2e418318784fcbd

Supported Donation Forms​

All donation forms on the https://donate.tiltify.com subdomain support relaying donations.

  • https://donate.tiltify.com/cause-slug?relay=<client_key>
  • https://donate.tiltify.com/cause-slug/fundraising-event-slug?relay=<client_key>
  • https://donate.tiltify.com/@username/campaign-slug?relay=<client_key>
  • https://donate.tiltify.com/+team-slug/team-campaign-slug?relay=<client_key>

4. Wait​

Depending on the payment method the user used to donate with the time it takes to receive a notification will vary.

If you need to check if a donation has begun processing, or view the current status of the donation, you can follow the reconciliation guide to get the current status of a given Relay Key.

5. Receive Relayed Donation Webhooks​

We will send webhooks for various changes of the relayed donation including:

  • When the donation has been completed. This means the donation was successful and has finished processing.
  • When the donation has been cancelled. This means the payment associated with the donation has been refunded to the donor.
  • If the donation has been moderated or unmoderated. This means that the Event owner decided to change the moderation status the donation hiding the donor_name and donor_comment.

The payload will include a few extra fields that were used when generating the relay key:

  • meta.relay_id - This is the id of the Relay.
  • meta.relay_key_id - This is id of the Relay Key, it may be either the optional string that was passed when generating the Relay Key, or a uuid that was auto generated.
  • meta.relay_metadata - This is the optional metadata that was passed when generating the Relay Key.

Example Payload​

{
  "data": {
    "amount": {
      "currency": "USD",
      "value": "20.00"
    },
    "campaign_id": "2d4f019a-4e0e-491f-86e2-03f59e80d921",
    "cause_id": "1071561f-54ef-4c4f-a7ed-f9a4536eb5be",
    "completed_at": "2023-05-12T00:46:18.493622Z",
    "created_at": "2023-05-11T11:45:41.495861Z",
    "donor_comment": "Odit non et dignissimos consequatur aut qui sequi.",
    "donor_name": "Ledian",
    "fundraising_event_id": null,
    "id": "b5cbe2d5-4907-459c-8941-5330122d3fca",
    "legacy_id": 123456,
    "poll_id": null,
    "poll_option_id": null,
    "reward_id": null,
    "sustained": false,
    "target_id": null,
    "team_event_id": null
  },
  "meta": %{
    "attempted_at": "2023-05-12T00:45:27.832161Z",
    "event_type": "private:relay:donation_updated",
    "generated_at": "2023-05-12T00:45:27.775534Z",
    "id": "960a8f5a-1103-4234-83b3-e281b92126fc",
    "relay_id": "8e615ce4-9246-42d3-b3b2-b3fba2b55d2a",
    "relay_key_id": "internal_2OyjGiv8ODkZqhvjmA0vmsY49JT",
    "relay_metadata": "eyJjdXN0b20iOiJtZXRhZGF0YSJ9"
  }
}