Webhooks overview

What are webhooks?

A webhook is a message that is automatically sent between applications when a specific event occurs. It's the perfect way to connect applications and automate workflows. In Role.so's case you can seamlessly send applicant data — whether interested or declined — to any platform that supports webhooks, including Make, Zapier, and more.

Use cases and examples

You can automate and tailor your workflow to fit every scenario:

Send contact information submitted by interested candidates to a Google spreadsheet
Send an automated text message to a candidate who shown interest in a role
Send a notification in Slack when a candidate is interested or declines a role
Save candidate data to the application tracking system of your choice

Events

When creating a webhook, you can choose from two event types: Interested and Declined. These events map directly to the two forms present on every candidate pack. Once a form is submitted, we'll send a message to all your active webhooks matching the event type.

Data

Depending on the event type (interested or declined), we send a fixed data structure. You can use this data to create automations in your applications and enrich your workflow.

Interested data

{
  "contract_version": 1, // 📦 Webhook contract version
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Unique indentifier
  "action": "user_interested", // 🔔 Action type
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Date, as ISO string
  "source": "web_form", // 🌐 Event source
  "source_url": "https://role.so/packs/demo", // 🔌 Candidate pack link where the event occurred
  "payload": {
    "role": "Software Engineer", // 💼 Role, as configured on the candidate pack
    "company": "Acme Inc", // 🏢 Company, as configured on the candidate pack
    "user_details": {
      "name": "Jane Doe", // 👤 Name form field
      "email": "hello@example.com", // ✉️ Email form field
      "phone": "07900000000", // 📞 Phone form field
      "website": "https://linkedin.com", // 🌐 Website URL form field
      "attachments": [
        "https://role.so/mock_webhook_file_1.pdf",
        "https://role.so/mock_webhook_file_2.pdf"
      ], // 🔗 A list of files attached by the candidates
      "custom_answers": [
        {
          "label": "Availability",
          "value": "Immediately"
        }
      ] // 📝 Optional answers to custom questions
    }
  }
}

If no custom-question answers are submitted, the custom_answers property is omitted from the payload rather than set to null. Other unused or disabled scalar fields will be marked as null, while attachments is always an array and is [] when no files are uploaded. For example, if your candidate pack's interest form has only the name and email fields enabled, we'd send the following data:

{
  // The same data as above
  "payload": {
    "user_details": {
      "name": "Jane Doe",
      "email": "hello@example.com",
      "phone": null,
      "website": null,
      "attachments": []
    }
  }
}

Declined data

The decline data is similar in shape to the interest one:

{
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Unique indentifier
  "action": "user_declined", // 🔔 Action type
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Date, as ISO string
  "source": "web_form", // 🌐 Event source
  "source_url": "https://role.so/packs/demo", // 🔌 Candidate pack link where the event occurred
  "payload": {
    "role": "Software Engineer", // 💼 Role, as configured on the candidate pack
    "company": "Acme Inc", // 🏢 Company, as configured on the candidate pack
    "decline_reasons": ["Salary", "Perks", "Office location"] // 📋 A list of reasons for declining
  }
}

If you have custom decline reasons configured on your form, we'll send this data instead. For example, if you custom decline reasons are configured to Reason #1 and Reason #2, we'd send the following data:

{
  // The same data as above
  "payload": {
    "decline_reasons": ["Reason #1", "Reason #2"]
  }
}

Frequently Asked Questions

Q: Is this feature available on the `Starter` plan?

A: Access depends on the features included in your current plan. If your account includes the webhook entitlement, you can use this feature; otherwise, the dashboard will show the available upgrade options.

Q: How many webhooks can I create?

A: At the moment you can create a maximum of 4 webhooks.

Q: Are events/notifications send real-time?

A: In most of the cases yes, however it can take anywhere between 1 to 5 minutes for the data to be sent to your application.

Q: Can I send test events?

A: Yes, there is an option to send test notifications so you can easily set up your workflow without affecting the stats on your candidate packs. For more about this, have a look at Send a test event help article.

Q: How are failures handled?

A: Retryable failures, such as network errors, timeouts, HTTP 5xx responses, and selected transient 4xx responses, receive up to 8 delivery attempts in total: the initial attempt plus up to 7 retries. Permanent failures, such as invalid payloads, endpoints blocked by security policy, and other 4xx responses, stop after the first attempt. A webhook can be flagged as failing after an individual delivery failure, and a dead delivery can be retried manually. For more about this, have a look at Monitoring webhooks help article.

Q: What happens if a webhooks fails over time, will I be notified?

A: Not directly; however, we'll flag the webhook as failing and you'll see a Failing badge being added to your webhook. Persistent delivery failures do not automatically disable the webhook. Review the endpoint and disable the webhook manually from the webhooks page if needed. For more about this, have a look at Monitoring webhooks help article.