Skip to main content

​
Overview

Record Webhooks send import data to your system in batches in real-time. Receiving large amounts of data by webhook can be more complex than pulling data from the Fuse API, so you should only use Record Webhooks if you need to show backend validation errors to the user during import. Record Webhooks send data in batches of up to 1,000. An import with 10,000 records will have ten batches of records sent by webhook, each with 1,000 records.

​
Record Webhook Flow

There are three steps that you need to set up to get Record Webhooks working properly.

​
Step 1: Receive Batches

Fuse will send records to your webhook in batches of 1,000. The payload looks like this: 
{
  batch_slug: '77db4861-6205-4344-b234-2d3ca0f9439a',
  import_slug: '960e938b-b3ac-4948-8713-ea84fdc72121',
  batches_count: 10,
  records: [],
  complete: false,
  metadata: {
    // Object containing metadata related to the import session
  }
}
Here is the definition of each key in the payload:
  • batch_slug: A unique identifier for the batch.
  • import_slug: A unique identifier for the import.
  • batches_count: The number of batches that will be sent.
  • records: The records in the current batch.
  • complete: The final batch sent will have this marked as true.
Your server should respond to batches within 5 seconds. If you can process each batch in less than 5 seconds, you can give us an inline response telling us that the batch has been completed with any associated validation issues, as seen below. 
{
  batch: {
    status: 'completed',
    validation_issues: [{
      record_slug: '8971a303-8989-4b43-bb0b-dadf48bbace3',
      validation_type: 'error',
      column_name: 'email',
      issue_description: 'Email already exists and must be unique.'
    }]
  }
}
If your server might take longer than 5 seconds to process a batch, then you should process the batch in a background job and respond to our webhook telling us that the batch is still processing. 
{
  batch: {
    status: 'processing'
  }
}
Here is the definition of each key in the response payload:
  • status: Must be ‘completed’ if you have finished processing the batch, or ‘processing’ if, for example, you are processing the batch in a background job.
  • record_slug: The unique slug of the record.
  • validation_type: Must be ‘warning’ or ‘error’.
  • column_name: The internal_key from the column in Fuse.
  • issue_description: A user-facing message to show the user.

​
Step 2: Update Batch Status

If you responded with a status of processing to any batches in step 1, then you must update us once each batch has been completed. You can send an HTTP request to Fuse to update the status of your batch. 
PUT https://fuse.flatirons.com/api/v1/webhooks/batches/:batch_slug
Headers:
- Authorization: Bearer {API_KEY_TOKEN}
Body:
{
  batch: {
    status: 'completed',
    validation_issues: [{
      record_slug: 2,
      validation_type: 'error',
      column_name: 'email',
      issue_description: 'Email already exists and must be unique.'
    }]
  }
}

​
Security

See Webhook Security to verify record webhook requests.