Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.prelude.so/llms.txt

Use this file to discover all available pages before exploring further.

The migration.hook_failed event is triggered when Prelude calls your migration hook and the call cannot be completed successfully. Use this event to monitor the health of your migration endpoint and alert on outages or misconfiguration.

​
Failure reasons

The reason field identifies the precise rule that failed. It is one of the following values:

​
Transport-level

ReasonDescription
request_failedThe HTTP request to your migration hook could not be completed (DNS failure, connection refused, TLS error, timeout exceeding 5 seconds, etc.).
invalid_status_codeThe hook returned a non-2xx HTTP status code.

​
Response-level

The following reasons are emitted when the hook returns 200 but the body does not match the expected response schema:
ReasonDescription
response_decode_failedThe response body could not be parsed as JSON (malformed JSON, wrong content type, body exceeding the 64 KB limit, etc.).
missing_external_idThe response was missing the required external_id field on the user.
missing_identifiersThe response did not provide at least one identifier for the user.
invalid_responseFallback emitted when the response body is otherwise invalid — for example an unsupported identifier type, an invalid phone number or email, an unknown OAuth provider, or an invalid scope.

​
Event payload

Emitted when Prelude calls your migration hook and the call cannot be completed successfully.

​
reason
enum<string>
required

The reason the migration hook call failed. Transport-level reasons describe failures reaching the hook; response-level reasons describe failures validating the response body.

Available options:
request_failed,
invalid_status_code,
response_decode_failed,
missing_external_id,
missing_identifiers,
invalid_response
Example:

"missing_external_id"

​
occurred_at
string<date-time>
required
Example:

"2025-03-15T10:30:00Z"

​
dispatch_id
string
Example:

"123e4567-e89b-12d3-a456-426614174000"

​
correlation_id
string
Example:

"123e4567-e89b-12d3-a456-426614174000"