Create & Manage Webhooks

Example section for showcasing API endpoints

Webhooks are highly versatile tools that enable automation and provide status updates, making them particularly useful for polling processes. They are fully compatible with platforms like Zapier, Make, and n8n.

Adding a Webhook

Currently, webhooks cannot be added via the API. To add one manually through the Captain Data app:

1. Open one of your Runs and navigate to the Webhooks tab.

Navigate to Webhooks

2. Click Add Webhook to access a modal with available options.

Add Webhook Modal

3. Choose one of three event types:

   • Created: Triggered when a job starts and the first task launches.

   • Succeeded: Triggered when a job completes successfully.

     {
       "uid": "eaab7f39...",
       "job_uid": "b9a260de...",
       "message": "Job successfully finished.",
       "project_uid": "xxxxx...",
       "error": null,
       "recipe_ref": "b9a260de...",
       "workflow_uid": "edcee5c...",
       "workflow_name": "Extract LinkedIn Messages",
       "job_name": "Automated Run"
     }
     

   • Failed: Triggered when a job encounters an error.

     {
       "uid": "a8e9923c...",
       "job_uid": "88f0a5fb...",
       "message": "Job failed.",
       "project_uid": "xxxxx...",
       "error": "Error while completing action: cannot re-send connection request yet.",
       "recipe_ref": "88f0a5fb...",
       "workflow_uid": "edcee5c...",
       "workflow_name": "Connect LinkedIn Profile",
       "job_name": "Campaign connect with Leads"
     }
     

4. Once created, your webhook will be ready to use.

Webhook Created

Headers Configuration

In the webhook modal, you can configure custom headers for secure and formatted integrations:

• Header Name: Specify the key (e.g., Authorization, Content-Type).
• Header Value: Provide the value (e.g., Bearer token, application/json).

These headers ensure proper authentication and data formatting for external tools.

Webhook Payload

When triggered, a webhook sends a POST request with the following JSON payload:

{
  "uid": "The webhook UID",
  "job_uid": "The job UID the webhook has been triggered on.",
  "message": "Default message based on failure or success.",
  "project_uid": "Your project UID. Useful to integrate our API.",
  "error": "If there's an error, this key contains the error message."
}

Handling Job Results: Success vs. Failed Inputs

• Failed Status: Triggered if all inputs fail.
• Succeeded Status: Triggered if at least one input succeeds, even if others fail.

To investigate discrepancies between inputs and outputs, use the Get a Run’s Inputs API endpoint:

• API Reference: Get a Run’s Inputs
• Endpoint: https://api.captaindata.co/v3/jobs/{job_uid}/inputs

Common Reasons for Failed Inputs

• 404 Errors: The profile or resource is inaccessible.
• Incorrect Inputs: Invalid or improperly formatted inputs.
• Authentication Issues: For example, an invalid LinkedIn session cookie.

Example payload for authentication errors:

{
  "uid": "80149f56-a0e9-4b18-...",
  "job_uid": "92681a73-be6d-4114-..",
  "message": "Job failed.",
  "project_uid": "xxxxxxx-e8b3-445c-...",
  "error": "Your cookie is not valid. Update your LinkedIn integration's account by clicking on the refresh button if you have installed the extension or update it manually.",
  "recipe_ref": "xxxxxxx-be6d-4114-97d4-...",
  "workflow_uid": "dac53683-dc50-...",
  "workflow_name": "Extract LinkedIn People Profile",
  "job_name": "test invalid cookie"
}

Retrying Failed Inputs

Retries depend on the failure reason:

• Do Not Retry: Issues like 404 errors or incorrect inputs.
• Retry Possible: Temporary issues such as API timeouts or invalid session cookies.

To retry jobs:

1. Refresh and resume paused jobs.
2. Update your cookie or resolve the issue and retry. Retry a Run Guide

Retrying a Webhook

You can retry webhooks for:

• Testing: Re-trigger to validate the integration.
• Missed Webhooks: Reattempt delivery if the webhook wasn’t triggered.

Using the API

To retry a webhook, use the Retry Webhook endpoint:

curl --request POST \
--url https://api.captaindata.co/v3/webhooks/{job_uid}/retry \
--header 'Authorization: <api-key>' \
--header 'x-project-id: <api-key>'

Replace {job_uid} with the relevant job UID. For detailed instructions, refer to the Retry Webhook Documentation.

Retrying in the UI

To retry through the Captain Data app:

1. Open the specific job by its UID.
2. Navigate to the Webhooks tab.
3. Click Retry and paste the job UID to reattempt delivery.

Retry Webhook

By effectively utilizing webhooks, you can streamline workflows and receive real-time notifications for critical events.