Skip to content
Duel Dashboard
  • There are no suggestions because the search field is empty.

Using Webhooks in Duel

Webhooks allow brands to automatically receive real-time event data from Duel, removing the need to manually poll the API. This guide covers what webhooks are, how to set them up within the Duel platform, and common use cases for both technical and operational teams.

What Are Webhooks?
How to Set Up a Webhook
Webhook States Explained
Managing Existing Webhooks
Webhook Delivery History
Event Mapping (Coming Soon)

What Are Webhooks?

Webhooks provide a way for Duel to proactively send data to a brand’s system when specific events occur, such as an Advocate being accepted into a programme or a purchase being completed. This replaces the traditional method of polling the Events Endpoint, where a brand would routinely ask Duel for updates.

With webhooks:

  • Duel sends the data outbound when an event happens.

  • You can configure which events you want to receive.

  • Data is delivered instantly, allowing real-time responses in external systems.

How to Set Up a Webhook

1. Access the Webhooks Section

Navigate to: Duel Dashboard → Settings → Integrations → Webhooks

Note: You'll need admin access to see the integrations tab, reach out to the team if you don't yet have it.

2. Add Notification Emails

Before proceeding, please enter one or more email addresses to receive error notifications if a webhook fails. This step is required to ensure effective troubleshooting and successful testing.

3. Configure a New Webhook

Click “Configure New”, then complete the following fields:

Field

Description

Name

A unique name for the webhook configuration (e.g. CRM Sync).

Target URL

The public endpoint that will receive Duel’s events.

HTTP Method

Typically POST, which includes all event data. GET is available that'll only show data headers.

Events to Subscribe To

Select all or a selection of event types (e.g. Task Approvals, Advocate Purchases). See more info on our API article.

Rate Limiting

Controls how many events per second are sent to your endpoint. Useful for high-volume programmes.

Payload Signing

Optional security feature that verifies data came from Duel. A secret key is provided to support this.

State

Set the webhook to Active, Paused, or Disabled. See below for state behaviour.

Webhook States Explained

  • Active: Webhook is live and sending events.

  • Paused: Events are queued and held until reactivated.

  • Disabled: Events are discarded until reactivated.

Test Events

You can send sample (dummy) events for each supported type to verify that your endpoint is correctly receiving and handling data. These test payloads reflect real-world data structures and help you validate setup before going live.

Managing Existing Webhooks

From the Manage view, you can:

  • Update the target URL.

  • Modify subscribed events, rate limits, or payload signing.

  • Change the webhook state.

  • Send additional test events.

  • View webhook delivery history.

  • Delete a webhook (with confirmation).

Note: Once a webhook is deleted, its data cannot be recovered. Be sure before confirming deletion.

Webhook Delivery History

Duel integrates with Hookdeck, an infrastructure tool that tracks every webhook delivery attempt.

From the webhook history tab, you can inspect:

  • Event delivery status (e.g. success/failure).

  • Headers and payload body.

  • Response codes from the target system.

  • Delivery retries (if any).

This is especially useful for troubleshooting during setup or diagnosing issues later.

Event Mapping (Coming Soon)

A powerful upcoming feature, Event Mapping, allows brands to reshape webhook payloads before delivery. This is essential when integrating with platforms like Shopify or Salesforce that require a specific JSON structure.

For example:

  • Map task.id to a new key like custom_task_id

  • Remove unnecessary fields

  • Format data for downstream systems

This eliminates the need for middleware or transformation logic within your system.