EventsHookDelivery events.hook-delivery@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

Version
1.0.0
Owner
events
Visibility
public
Status
active
Compatibility
backward
Schema
https://openvibe.network/contracts/events/hook-delivery.v1.json

events.hook-delivery@1: one attempt by OpenVibe.Events to deliver an event to a hook. It carries the outcome, timing, size and hash of the payload, never the payload itself, its headers, the signature or the hook's secret. A delivery is retried inside its hook's window and dead-lettered after it; replay creates a new attempt that names the one it replays.

Fields

FieldTypeRequiredDescriptionConstraints
idstringyes
  • pattern ^whd_[0-9A-HJKMNP-TV-Z]{26}$
hook_idstringyes
  • pattern ^hok_[0-9A-HJKMNP-TV-Z]{26}$
event_idstringyes
  • pattern ^evt_[0-9A-HJKMNP-TV-Z]{26}$
event_typestringyes
  • pattern ^[a-z][a-z0-9_]*(\.[a-z0-9_]+){2,}$
attemptintegeryes
  • minimum 1
  • maximum 100
statusenumyesfailed is a retryable attempt; dead is the last, after the hook's window. A 2xx answer marks delivered.
  • one of "queued", "delivering", "delivered", "failed", "dead"
request_idstring | nullThe delivery request id, for tracing; not a secret.
  • maxLength 64
response_codeinteger | null
  • minimum 100
  • maximum 599
latency_msinteger | null
  • minimum 0
payload_bytesintegeryes
  • minimum 0
  • maximum 1048576
payload_sha256stringyesThe SHA-256 of the signed body, so a consumer can check it without the body being stored here.
  • pattern ^[0-9a-f]{64}$
signature_versionconst
  • = "v2"
next_attempt_atstring | null
  • format date-time
attempted_atstring | null
  • format date-time
completed_atstring | null
  • format date-time
dead_atstring | null
  • format date-time
errorstring | nullA short transport or status reason; never a response body.
  • maxLength 400
replay_ofstring | nullThe failed or dead attempt this one replays.
  • pattern ^whd_[0-9A-HJKMNP-TV-Z]{26}$
created_atstringyes
  • format date-time

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: dead
{
  "id": "whd_01J8Z3Q4R5S6T7V8W9X0Y1Z2B1",
  "hook_id": "hok_01J8Z3Q4R5S6T7V8W9X0Y1Z2A9",
  "event_id": "evt_01J8Z3Q4R5S6T7V8W9X0Y1Z2B0",
  "event_type": "github.push.received",
  "attempt": 30,
  "status": "dead",
  "response_code": null,
  "latency_ms": null,
  "payload_bytes": 2048,
  "payload_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "next_attempt_at": null,
  "attempted_at": "2026-11-05T09:00:00.000Z",
  "completed_at": "2026-11-05T09:00:01.000Z",
  "dead_at": "2026-11-05T09:00:01.000Z",
  "error": "share offline",
  "replay_of": null,
  "created_at": "2026-10-29T09:00:00.000Z"
}
Valid: delivered
{
  "id": "whd_01J8Z3Q4R5S6T7V8W9X0Y1Z2B1",
  "hook_id": "hok_01J8Z3Q4R5S6T7V8W9X0Y1Z2A9",
  "event_id": "evt_01J8Z3Q4R5S6T7V8W9X0Y1Z2B0",
  "event_type": "github.push.received",
  "attempt": 1,
  "status": "delivered",
  "request_id": "req_01J8Z3Q4R5S6T7V8W9",
  "response_code": 202,
  "latency_ms": 84,
  "payload_bytes": 2048,
  "payload_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "signature_version": "v2",
  "next_attempt_at": null,
  "attempted_at": "2026-10-29T09:00:00.000Z",
  "completed_at": "2026-10-29T09:00:00.084Z",
  "dead_at": null,
  "error": null,
  "replay_of": null,
  "created_at": "2026-10-29T09:00:00.000Z"
}
Rejected: bad-hash
{
  "id": "whd_01J8Z3Q4R5S6T7V8W9X0Y1Z2B1",
  "hook_id": "hok_01J8Z3Q4R5S6T7V8W9X0Y1Z2A9",
  "event_id": "evt_01J8Z3Q4R5S6T7V8W9X0Y1Z2B0",
  "event_type": "github.push.received",
  "attempt": 1,
  "status": "delivered",
  "payload_bytes": 2048,
  "payload_sha256": "not-a-sha256",
  "created_at": "2026-10-29T09:00:00.000Z"
}
Rejected: body-field
{
  "id": "whd_01J8Z3Q4R5S6T7V8W9X0Y1Z2B1",
  "hook_id": "hok_01J8Z3Q4R5S6T7V8W9X0Y1Z2A9",
  "event_id": "evt_01J8Z3Q4R5S6T7V8W9X0Y1Z2B0",
  "event_type": "github.push.received",
  "attempt": 1,
  "status": "delivered",
  "payload_bytes": 2048,
  "payload_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "body": "{\"ref\":\"refs/heads/main\"}",
  "created_at": "2026-10-29T09:00:00.000Z"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('events.hook-delivery@1', value);   // { valid, errors: [{ path, message }] }