Search

🪝

Webhooks

About webhooks

💡

Webhooks let BettrData notify your application when a file or job reaches a particular step. Use them to send operational alerts, update an internal dashboard, or start a downstream workflow.

BettrData sends an HTTP POST request with a JSON body to the URL you configure. You provide the receiving endpoint and choose which events it should receive.

Configure Webhooks

  1. Open Admin → System Settings → Global.
  2. Find Webhooks.
  3. Enter your receiving URL beside each event you want to receive, such as https://integrations.example.com/bettrdata/webhooks. You can use the same URL for several events or different URLs for different workflows.
  4. Optionally configure Default Webhook as a fallback and Global Headers for authentication. Both settings are explained after the event reference, in their on-screen order.
  5. Click Save in the Webhooks section.

Use an HTTPS endpoint that BettrData can reach. If you cannot edit these settings, ask your administrator to configure them. To stop receiving a particular event, clear its URL and save; if Default Webhook is set, that event will still be sent to the default URL.

Prepare your receiving endpoint

  • Accept HTTP POST requests with Content-Type: application/json.
  • Check any authentication header you have configured.
  • Parse the JSON and route your handling logic using the top-level event value.
  • Return a successful HTTP response promptly after accepting the notification. A simple 200 OK with {"received": true} is suitable.
  • Queue lengthy downstream work so that your endpoint responds quickly.

Understand the payload

Field
Meaning
event
Exact event identifier, such as created or load-failed. Use this field to decide what happened.
status
Human-readable status assigned to this event. Several events share a status; it is not a unique event identifier or a guarantee that the entire workflow is complete.
file
File metadata for file-related events. Typically includes _id and fileName, with other properties depending on the processing stage. Merge events use run instead.
run
Conversion run for conversion/external processing events, or merge run for merge events. Use run._id to identify the attempt/job.
convertRun
Conversion run attached to load events when available. This is a different field name from run.
report
Conversion report for Convert Success and Validation Failed when available; explicitly null for external processing events. Reports can include record counts and other results.

All JSON examples below are simplified payload excerpts with fictional values. Actual requests can contain additional nested metadata, status details, configuration, and report fields. Fields may be absent or null depending on the event and processing stage. Accept additional fields and check optional fields before using them. Example IDs are illustrative placeholders.

The top-level status is a string; nested file.status and run.status values are objects. In particular, a load-failed event can have top-level status: "Convert Complete" because conversion completed before the load failed.

Event reference

The following event headings use the labels and order shown under Admin → System Settings → Global → Webhooks. This is the settings order, rather than a guaranteed delivery sequence.

File Created

Event: created · Status: Processing

Sent when a new file is received and registered. Use this to record incoming files or start intake notifications. The file may not yet have a format, schema, or record count.

{
  "event": "created",
  "status": "Processing",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

Parent File Identified

Event: parent · Status: Will Not Convert

Sent when intake identifies a parent file, such as a container that will produce child files. The parent is not converted as a normal data file; its children follow their own processing lifecycle.

{
  "event": "parent",
  "status": "Will Not Convert",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

Virtual File Created

Event: vf-created · Status: Processing

Sent when conversion creates a virtual file. The file object describes the new virtual file, rather than the original input file.

{
  "event": "vf-created",
  "status": "Processing",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers-virtual.csv",
    "virtual": true
  }
}

Processing Success

Event: processing-success · Status: Processing

Sent when initial file processing completes successfully. This covers intake and identification work; conversion, validation, and delivery can still follow. It does not mean the file has loaded to its destination.

{
  "event": "processing-success",
  "status": "Processing",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

Processing Failure

Event: processing-failed · Status: Processing

Sent when initial file processing fails, including intake or file availability problems. Check the file in Data Management and inspect file.status.processed.error when present before retrying.

{
  "event": "processing-failed",
  "status": "Processing",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv",
    "status": {
      "processed": {
        "error": "File is no longer on route"
      }
    }
  }
}

Header Validation Failure

Event: header-validation-failed · Status: Waiting to Convert

Sent when header validation prevents automatic conversion from proceeding. Review the headers and mapping in the builder. An error may be included in file.status.converted.error.

{
  "event": "header-validation-failed",
  "status": "Waiting to Convert",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv",
    "status": {
      "converted": {
        "error": "Header validation failed. 'Open in Builder' to review."
      }
    }
  }
}

File Duplicate

Event: duplicate · Status: Processing

Sent when intake detects another file with the same content checksum. Whether processing continues depends on the duplicate handling configuration or a forced reprocess; this notification alone does not confirm that the duplicate was rejected.

{
  "event": "duplicate",
  "status": "Processing",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

Convert Started

Event: convert-started · Status: Converting

Sent when a conversion run starts. Use run._id to correlate notifications for that conversion attempt.

{
  "event": "convert-started",
  "status": "Converting",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  },
  "run": {
    "_id": "convert-example-001"
  }
}

Convert Failed

Event: convert-failed · Status: Waiting to Convert

Sent when a conversion run returns a nonzero exit code. Inspect run.status.exitCode, run.status.error when present, and the conversion logs before retrying.

{
  "event": "convert-failed",
  "status": "Waiting to Convert",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  },
  "run": {
    "_id": "convert-example-001",
    "status": {
      "exitCode": 1
    }
  }
}

Convert Success

Event: converted · Status: Waiting for Review

Sent after conversion succeeds. A conversion report is included when available. Conversion success is separate from validation approval and loading to the configured destination.

Validation Success

Event: reviewed · Status: Convert Complete

Sent when a converted file is marked as reviewed, either automatically or manually. This means review is complete; use Load Success to confirm destination delivery.

{
  "event": "reviewed",
  "status": "Convert Complete",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

Validation Failed

Event: validation-failed · Status: Waiting for Review

Sent when automatic validation does not approve a converted file. Review the conversion report and validation results in the application. This event is separate from a conversion execution failure, and is not emitted for every manual review outcome.

Load Success

Event: loaded · Status: Convert Complete

Sent when a validated file finishes loading or transferring to its configured destination. The conversion attempt is provided as convertRun, rather than run. Use this event for downstream actions that depend on delivery.

{
  "event": "loaded",
  "status": "Convert Complete",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  },
  "convertRun": {
    "_id": "convert-example-001"
  }
}

Load Failed

Event: load-failed · Status: Convert Complete

Sent when loading or transferring to the destination fails. Check file.status.loaded.error when present and review destination access and load logs. convertRun is included when available and can be absent on some failure paths. The top-level status remains Convert Complete; the event identifies the load failure.

File Deleted

Event: deleted · Status: Waiting to Convert

Sent after converted output is deleted through the application's delete/trash workflow. This can make a file available for conversion again; it does not mean that the source file record has been permanently removed. Use Purge Success for purge completion.

{
  "event": "deleted",
  "status": "Waiting to Convert",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

File Unidentified

Event: unidentified · Status: Unidentified

Sent when intake cannot identify the required file type, format, or length. Review the file and assign or correct its schema/mapping before continuing.

{
  "event": "unidentified",
  "status": "Unidentified",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

Missing Convert

Event: missingconvert · Status: Waiting to Convert

Sent when automatic conversion cannot find or create a usable mapping and the file remains waiting to convert. Create or select the appropriate mapping in the application.

{
  "event": "missingconvert",
  "status": "Waiting to Convert",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

External Process Send Success

Event: eip-send · Status: Converting

Sent after a file is successfully submitted to a configured external processing service. This confirms submission, rather than completion of external processing.

{
  "event": "eip-send",
  "status": "Converting",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  },
  "run": {
    "_id": "convert-example-001"
  },
  "report": null
}

External Process Return Success

Event: eip-return · Status: Converting

Sent when the external processing return workflow locates the returned work and resumes processing. Further conversion and delivery steps may still be required.

{
  "event": "eip-return",
  "status": "Converting",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  },
  "run": {
    "_id": "convert-example-001"
  },
  "report": null
}

External Process Failure

Event: eip-fail · Status: Waiting to Convert

Sent when external processing submission or the return conversion fails. Inspect the external processing and conversion logs. The event includes the conversion run and report: null.

{
  "event": "eip-fail",
  "status": "Waiting to Convert",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  },
  "run": {
    "_id": "convert-example-001"
  },
  "report": null
}

Merge Job Started

Event: merge-started · Status: Converting

Sent when a merge job starts. Merge notifications contain a merge run and do not contain a top-level file. Correlate the job using run._id.

{
  "event": "merge-started",
  "status": "Converting",
  "run": {
    "_id": "merge-example-001",
    "description": "Combine customer files"
  }
}

Merge Job Success

Event: merge-success · Status: Convert Complete

Sent when a merge job finishes with exit code 0. The payload contains the merge run. Subsequent production workflow or delivery steps may still follow.

{
  "event": "merge-success",
  "status": "Convert Complete",
  "run": {
    "_id": "merge-example-001",
    "description": "Combine customer files",
    "status": {
      "done": true,
      "exitCode": 0
    }
  }
}

Merge Failed

Event: merge-failed · Status: Will Not Convert

Sent when a merge job finishes with a nonzero exit code. Review the merge job, its inputs, and its logs before retrying.

{
  "event": "merge-failed",
  "status": "Will Not Convert",
  "run": {
    "_id": "merge-example-001",
    "description": "Combine customer files",
    "status": {
      "done": true,
      "exitCode": 1
    }
  }
}

Purge Success

Event: purge-success · Status: Will Not Convert

Sent after a purge completes and the file is marked as purged. Purging removes applicable stored input/output files according to the configured workflow; it is separate from deleting converted output. The file metadata can remain available.

{
  "event": "purge-success",
  "status": "Will Not Convert",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv",
    "status": {
      "purged": {
        "done": true
      }
    }
  }
}

Default Webhook

Default Webhook is a routing setting, rather than a separate event type. Enter a URL here to receive events that do not have an event-specific URL configured.

  • An event-specific URL takes priority over Default Webhook.
  • The default is a fallback; it does not receive a second copy when an event-specific URL is used.
  • If neither URL is set, no external notification is sent for that event.

The body keeps the original event name. For example, a File Created notification delivered to the default URL still looks like this:

{
  "event": "created",
  "status": "Processing",
  "file": {
    "_id": "file-example-001",
    "fileName": "customers.csv"
  }
}

Global Headers

Global Headers adds the same custom HTTP headers to every outgoing webhook, including those sent to Default Webhook. Use this to supply an authentication header expected by your receiver.

For example, if your receiver expects a shared secret:

X-Webhook-Secret: replace-with-your-shared-secret

Enter X-Webhook-Secret as the Key and your actual secret as the Value. Use the lock controls to enter and lock the value, click Add, then Save. Your receiving service must validate the header.

Because these headers apply to all webhook destinations, use only endpoints that are authorized to receive them. Do not include real secrets in public examples or support screenshots.

Test and troubleshoot

Test your integration

  1. Configure an endpoint you control and save the settings.
  2. Trigger the corresponding activity using a sample file or job. Saving a webhook URL does not itself generate an event.
  3. Confirm that your receiver gets a POST, the expected event, and any configured headers.
  4. Check your receiver's response and confirm that its downstream action completes.
  5. If you use a default URL, also test an event without an event-specific URL.

A file will not necessarily emit every event: parent, virtual-file, external processing, merge, and failure events depend on the workflow. Processing Success, Convert Success, Validation Success, and Load Success describe different milestones.

If a notification is missing

  • Confirm that the settings were saved and that the expected activity actually occurred.
  • Check whether an event-specific URL routed the notification somewhere other than Default Webhook.
  • Verify endpoint reachability, TLS configuration, and authentication on your receiving service.
  • Inspect receiver logs for rejected requests or JSON parsing errors.
  • For assistance, provide the event name, file or run ID, and approximate time. Share payloads and logs only through an appropriate private support channel.

Handle repeated events and delivery failures

Make downstream actions safe to repeat: reprocessing a file or rerunning a job can produce additional notifications. Where a run ID is supplied, use the event and run ID to correlate the attempt. For file-only events, use the file ID with available version or processing details to distinguish legitimate later activity.

Do not assume a guaranteed event order, a unique webhook delivery ID, or automatic retry/replay. The current webhook flow does not provide a configured retry queue or replay control. Keep receiver-side logs and reconcile important outcomes with the file or job in BettrData when needed.