Set up webhooks

How webhooks work in Tallyfy

Section titled “How webhooks work in Tallyfy”

Tallyfy webhooks send automated JSON messages to external systems when specific workflow events happen. They POST data to URLs you define, giving you real-time integration with other apps. This guide covers how to set them up and avoid common pitfalls.

Webhook types

Section titled “Webhook types”

Tallyfy has two webhook levels:

Template-level webhooks

Section titled “Template-level webhooks”

Template-level webhooks fire when any step in a process is completed, when a process is launched, or when a process is completed. They send the full process data - all form fields and step statuses. Think of these as the “firehose” option.

They leave out top secret tasks, other than the task that fired the webhook. A top secret task is one that only administrators and its assignees can see. Top secret tasks lists what’s left out.

When a step has its own webhook URL set, that takes priority over the template-level webhook for that specific step.

Use cases:

• Track overall process progress in external systems
• Update dashboards when any step changes
• Capture new process launches or completions

Step-level webhooks

Section titled “Step-level webhooks”

Step-level webhooks fire only when a specific step is completed. More surgical - they only trigger when that particular step is done.

Use cases:

• Send notifications at key process milestones
• Trigger follow-up actions in other systems
• Export form field data collected at a particular step

How webhook events flow

Section titled “How webhook events flow”

This diagram shows how Tallyfy sends webhook data to external systems when events occur in your workflows.

What to notice:

• Two trigger types - Template-level webhooks fire on any step completion, process launch, or process completion. Step-level webhooks only fire for that specific step.
• Priority - If a step has its own webhook URL, it’s used instead of the template-level webhook for that step’s completion event.
• Organization ID header - Every webhook request carries an X-Tallyfy-orgID header. It identifies the organization that sent it, but it doesn’t secure anything.

Setting up template-level webhooks

Section titled “Setting up template-level webhooks”

1. Navigate to the template you want to configure
2. Click Edit to enter template editing mode
3. Open the Advanced Settings drawer
4. Find the Webhooks section
5. Toggle webhook functionality on
6. Enter the destination URL in the Template webhook URL field
7. Note the Template alias - you’ll need it in your integration

Setting up step-level webhooks

Section titled “Setting up step-level webhooks”

1. Navigate to the template containing your target step
2. Click Edit to enter template editing mode
3. Select the specific step that should trigger the webhook
4. Open the Advanced tab
5. Toggle webhook functionality on
6. Enter the destination URL in the webhook URL field
7. Save your changes

You can also send a webhook from an automation, so it fires only when the conditions you set are met.

Example: Slack notifications via middleware

Section titled “Example: Slack notifications via middleware”

Here’s how to send Slack notifications when an employee completes an onboarding step in Tallyfy.

What you’ll need

Section titled “What you’ll need”

• Tallyfy account with Professional or Enterprise plan
• Middleware account (Make.com, Power Automate, n8n, or Zapier)
• Slack workspace with admin access

Choosing the right middleware

Compare different middleware platforms based on your needs. Popular options include n8n, Make, Microsoft Power Automate, and Zapier - each with different pricing and capabilities.

For maximum control, especially if you have dev resources, consider using Tallyfy’s Open API to build custom integrations with AI-generated code for serverless functions.

Step 1: Set up the middleware webhook receiver

Section titled “Step 1: Set up the middleware webhook receiver”

1. Sign in to your middleware platform

2. Create a new workflow (“Zap” in Zapier, “Flow” in Power Automate, “Scenario” in Make)

3. Select Webhooks as the trigger app

4. Choose Catch Hook or When HTTP request is received as the trigger event

   

5. Copy the webhook URL provided by your middleware platform - you’ll paste it into Tallyfy next

   

Step 2: Configure the Slack message action

Section titled “Step 2: Configure the Slack message action”

1. Add an action step to your workflow.

2. Select Slack as the action app.

3. Choose Send Channel Message as the action event.

   

4. Connect your Slack account if not already connected.

5. Select the destination channel (e.g., #general).

6. Build a message template using the webhook data fields.

   

7. Include details like process name, step name, and assignee.

Step 3: Configure the Tallyfy webhook

Section titled “Step 3: Configure the Tallyfy webhook”

1. Navigate to your onboarding template in Tallyfy.
2. Enter Edit mode.
3. For template-level notifications, open the Advanced Settings drawer.
4. Toggle webhooks on.
5. Paste the middleware webhook URL into the Template webhook URL field.
6. For step-specific notifications, select the relevant step instead.
7. Open the Advanced tab for that step.
8. Toggle webhooks on and paste the middleware webhook URL.
9. Save your changes.

Step 4: Test the integration

Section titled “Step 4: Test the integration”

1. Run your onboarding process

2. Complete the relevant step

3. Verify the notification appears in your Slack channel

   

Security

Section titled “Security”

Tallyfy includes the X-Tallyfy-orgID header in all webhook requests. It identifies the sender: compare it with your organization ID to see which Tallyfy organization a request came from. It doesn’t prove the request came from Tallyfy, because the organization ID appears in Tallyfy links such as guest links, and anyone who knows it can send the same header. The payload structure page lists every header Tallyfy sends.

Handle duplicate webhook events

Webhooks can fire multiple times for the same event. For example, if a task is completed, then reopened and completed again, you’ll get multiple notifications. Always implement idempotency handling to prevent duplicate actions. It’s much easier to handle this from the start than debug it later.

Troubleshooting

Section titled “Troubleshooting”

Webhooks not firing? Here’s how to diagnose:

1. Verify the URL is correct - Copy and paste it fresh, don’t type it manually
2. Use a public URL - Tallyfy can’t send to localhost, so the address must be reachable from the internet. Send it a test request with Postman first
3. Confirm webhook is enabled - Both the toggle AND the URL field must be set
4. Check for HTTPS - Many receivers require HTTPS, not HTTP
5. Look for auth requirements - Your receiver might be rejecting unauthenticated requests
6. Verify step completion - Webhooks only fire when steps are actually completed (not just opened)
7. Return a 2xx status code within 10 seconds - Anything else, or no answer in time, counts as a failed attempt
8. Check your server logs - Look there for the incoming webhook event

Testing webhooks

Always test with webhook.site first. Get a unique URL there, use it in Tallyfy, then complete a task. You’ll see exactly what data Tallyfy sends. Once you’ve confirmed data is flowing, switch to your real webhook URL.

Webhook delivery behavior

Tallyfy makes up to 3 attempts at each webhook delivery. An attempt fails when your server can’t be reached, takes longer than 10 seconds to answer, or answers with anything other than a 2xx status. After a failed first attempt, Tallyfy waits 30 seconds and tries again. After a failed second attempt, it waits 300 seconds (5 minutes) and tries one last time before giving up. Deliveries, retries, and failures are recorded for the System Log, whose screens ship with the new Tallyfy client and aren’t generally available yet.

Best practices

Section titled “Best practices”

• Use HTTPS URLs for webhook destinations - HTTP is asking for trouble
• Read the X-Tallyfy-orgID header to see which organization sent a request, but don’t treat it as proof that Tallyfy sent it
• Test webhooks before relying on them in production
• Monitor webhook delivery using your middleware platform’s logs
• Build retry logic into your receiving system for reliability
• Use webhook.site or RequestBin for initial testing before connecting production systems
• Validate the payload structure on your end - don’t assume it won’t change

Starting a Tallyfy process from another system

Section titled “Starting a Tallyfy process from another system”

Webhooks send data out of Tallyfy. To go the other way, and launch a process from an external form or capture a guest’s details:

1. Call the API’s process launch endpoint.
2. Pass the form data as kick-off form values.
3. Include the guest’s email in the payload for automatic assignment.
4. A webhook can tell your system when the process starts.

Related articles

Section titled “Related articles”

Webhooks > Webhook scenarios

Tallyfy webhooks push JSON data to external systems when processes launch, complete, or when…

Integrations > Webhooks

Tallyfy webhooks automatically send structured JSON data to any external system via HTTP POST…

Webhooks > Send emails using webhooks

Connect Tallyfy webhooks to middleware tools like Zapier or Make to automatically send custom…

Webhooks > Webhook payload structure

Tallyfy webhook payloads deliver JSON data in two formats. Process-level payloads contain full…