Migration Hook Failed

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

Reason	Description
`request_failed`	The HTTP request to your migration hook could not be completed (DNS failure, connection refused, TLS error, timeout exceeding 5 seconds, etc.).
`invalid_status_code`	The 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:

Reason	Description
`response_decode_failed`	The response body could not be parsed as JSON (malformed JSON, wrong content type, body exceeding the 64 KB limit, etc.).
`missing_external_id`	The response was missing the required `external_id` field on the user.
`missing_identifiers`	The response did not provide at least one identifier for the user.
`invalid_response`	Fallback 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"

Documentation

API Reference

Failure reasons

Transport-level

Response-level

Event payload

​Failure reasons

​Transport-level

​Response-level

​Event payload

Failure reasons

Transport-level

Response-level

Event payload