Hubfly spaceDocs
Console

Managed Streams API · Dashboard

Webhooks & domains

Signed event webhooks with delivery logs and tests, and your own domains for playback and ingest.

Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.

Stream servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the stream server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the stream permissions must hold that exact permission.

How to use these endpoints

  1. Create a webhook for an https URL on port 443 or 8443. Its whsec_ secret is returned once; verify every delivery's Hubfly space-Signature with it.
  2. Send a test delivery, and read the delivery log to see status codes and retries.
  3. Add a custom domain for playback, ingest or both, point a CNAME at your server host, then verify it.

Subscribe to live and recording events

curl
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/stream/webhooks/create" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/hubfly/stream","events":["channel.live","channel.offline","recording.completed"]}'

The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.

Endpoint reference

Dashboard endpoints (10)

These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.

Open interactive API explorer
POSTAdd a custom domainDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/domains/create

Add a hostname for this server's playback, ingest or both (purpose, default playback) and return the cnameTarget, the server's <slug>.live.hubfly.app host, to point a CNAME at. The domain serves traffic once it is verified.

  • Requires stream:admin.
  • Hostnames are lower-case DNS names outside hubfly.app, hubfly.space and hubmail.space (422 STREAM_INVALID, code invalid_domain); a hostname already in use returns 409 STREAM_DOMAIN_TAKEN.
  • A server holds up to 10 domains.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
hostnamestringYes
purposeboth | playback | ingestNo
Complete request schema
{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string"
    },
    "purpose": {
      "type": "string",
      "enum": [
        "both",
        "playback",
        "ingest"
      ]
    }
  },
  "required": [
    "hostname"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "domain": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "hostname": {
                  "type": "string"
                },
                "purpose": {
                  "type": "string",
                  "enum": [
                    "both",
                    "playback",
                    "ingest"
                  ]
                },
                "verified": {
                  "type": "boolean"
                },
                "verifiedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastCheckAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastCheckError": {
                  "type": "string",
                  "nullable": true
                },
                "failedChecks": {
                  "type": "number"
                },
                "cnameTarget": {
                  "type": "string"
                },
                "revision": {
                  "type": "number"
                },
                "createdByUserId": {
                  "type": "string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "updatedAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "hostname",
                "purpose",
                "verified",
                "verifiedAt",
                "lastCheckAt",
                "lastCheckError",
                "failedChecks",
                "cnameTarget",
                "revision",
                "createdByUserId",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            },
            "cnameTarget": {
              "type": "string"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "domain",
            "cnameTarget",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "domain": {
          "id": "string",
          "hostname": "string",
          "purpose": "both",
          "verified": true,
          "verifiedAt": "string",
          "lastCheckAt": "string",
          "lastCheckError": "string",
          "failedChecks": 0,
          "cnameTarget": "string",
          "revision": 0,
          "createdByUserId": "string",
          "createdAt": "string",
          "updatedAt": "string"
        },
        "cnameTarget": "string",
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList custom domainsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/domains

List the server's custom domains with their purpose, verification state, last DNS check and error, consecutive failed checks and cnameTarget.

  • Requires stream:read.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "hostname": {
                "type": "string"
              },
              "purpose": {
                "type": "string",
                "enum": [
                  "both",
                  "playback",
                  "ingest"
                ]
              },
              "verified": {
                "type": "boolean"
              },
              "verifiedAt": {
                "type": "string",
                "description": "Date string",
                "nullable": true
              },
              "lastCheckAt": {
                "type": "string",
                "description": "Date string",
                "nullable": true
              },
              "lastCheckError": {
                "type": "string",
                "nullable": true
              },
              "failedChecks": {
                "type": "number"
              },
              "cnameTarget": {
                "type": "string"
              },
              "revision": {
                "type": "number"
              },
              "createdByUserId": {
                "type": "string",
                "nullable": true
              },
              "createdAt": {
                "type": "string",
                "description": "Date string"
              },
              "updatedAt": {
                "type": "string",
                "description": "Date string"
              }
            },
            "required": [
              "id",
              "hostname",
              "purpose",
              "verified",
              "verifiedAt",
              "lastCheckAt",
              "lastCheckError",
              "failedChecks",
              "cnameTarget",
              "revision",
              "createdByUserId",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": [
        {
          "id": "string",
          "hostname": "string",
          "purpose": "both",
          "verified": true,
          "verifiedAt": "string",
          "lastCheckAt": "string",
          "lastCheckError": "string",
          "failedChecks": 0,
          "cnameTarget": "string",
          "revision": 0,
          "createdByUserId": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETERemove a custom domainDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/domains/:domainId/delete

Remove a custom domain; the server stops answering on it once the node applies the change.

  • Requires stream:admin.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
domainIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "deleted": {
              "const": true,
              "type": "boolean"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "deleted",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "deleted": true,
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTVerify a custom domainDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/domains/:domainId/verify

Check DNS now: the hostname needs a CNAME to cnameTarget or, for an apex domain, A records that all point at the node's address. A verified domain is added to the server's configuration and gets its certificate from the node.

  • Requires stream:admin.
  • A failed check is not an error response: error says what DNS shows instead.
  • Verified domains are re-checked every 6 hours; after 3 failed checks in a row a domain is unverified and no longer served.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
domainIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "domain": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "hostname": {
                  "type": "string"
                },
                "purpose": {
                  "type": "string",
                  "enum": [
                    "both",
                    "playback",
                    "ingest"
                  ]
                },
                "verified": {
                  "type": "boolean"
                },
                "verifiedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastCheckAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastCheckError": {
                  "type": "string",
                  "nullable": true
                },
                "failedChecks": {
                  "type": "number"
                },
                "cnameTarget": {
                  "type": "string"
                },
                "revision": {
                  "type": "number"
                },
                "createdByUserId": {
                  "type": "string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "updatedAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "hostname",
                "purpose",
                "verified",
                "verifiedAt",
                "lastCheckAt",
                "lastCheckError",
                "failedChecks",
                "cnameTarget",
                "revision",
                "createdByUserId",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            },
            "verified": {
              "type": "boolean"
            },
            "error": {
              "type": "string",
              "nullable": true
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false,
              "nullable": true
            }
          },
          "required": [
            "domain",
            "verified",
            "error",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "domain": {
          "id": "string",
          "hostname": "string",
          "purpose": "both",
          "verified": true,
          "verifiedAt": "string",
          "lastCheckAt": "string",
          "lastCheckError": "string",
          "failedChecks": 0,
          "cnameTarget": "string",
          "revision": 0,
          "createdByUserId": "string",
          "createdAt": "string",
          "updatedAt": "string"
        },
        "verified": true,
        "error": "string",
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCreate a webhookDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/webhooks/create

Subscribe an HTTPS endpoint to server events. The node signs every delivery with HMAC-SHA256 (Hubfly space-Signature: t=…,v1=…) using the returned whsec_ secret, and retries failures 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours later.

  • Requires stream:admin.
  • The secret is returned once, with cache-control: no-store.
  • url must be https on port 443 or 8443 and resolve to public addresses; otherwise 422 STREAM_INVALID (code invalid_url).
  • events lists event types; [] or ["*"] subscribes to every type. A server holds up to 10 webhooks.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
urlstringYes
eventsstring[]No
enabledbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "webhook": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "events": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "enabled": {
                  "type": "boolean"
                },
                "fingerprint": {
                  "type": "string"
                },
                "revision": {
                  "type": "number"
                },
                "createdByUserId": {
                  "type": "string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "updatedAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "url",
                "events",
                "enabled",
                "fingerprint",
                "revision",
                "createdByUserId",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            },
            "secret": {
              "type": "string"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "webhook",
            "secret",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "webhook": {
          "id": "string",
          "url": "string",
          "events": [
            "string"
          ],
          "enabled": true,
          "fingerprint": "string",
          "revision": 0,
          "createdByUserId": "string",
          "createdAt": "string",
          "updatedAt": "string"
        },
        "secret": "string",
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList webhooksDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/webhooks

List the server's webhooks with their URL, subscribed events, enabled state and secret fingerprint. Secrets are never returned.

  • Requires stream:read.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "enabled": {
                "type": "boolean"
              },
              "fingerprint": {
                "type": "string"
              },
              "revision": {
                "type": "number"
              },
              "createdByUserId": {
                "type": "string",
                "nullable": true
              },
              "createdAt": {
                "type": "string",
                "description": "Date string"
              },
              "updatedAt": {
                "type": "string",
                "description": "Date string"
              }
            },
            "required": [
              "id",
              "url",
              "events",
              "enabled",
              "fingerprint",
              "revision",
              "createdByUserId",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false
          }
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": [
        {
          "id": "string",
          "url": "string",
          "events": [
            "string"
          ],
          "enabled": true,
          "fingerprint": "string",
          "revision": 0,
          "createdByUserId": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEDelete a webhookDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/webhooks/:webhookId/delete

Delete a webhook and its secret; the node stops delivering to it once it applies the change.

  • Requires stream:admin.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
webhookIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "deleted": {
              "const": true,
              "type": "boolean"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "deleted",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "deleted": true,
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList webhook deliveriesDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/webhooks/:webhookId/deliveries

Return the node's delivery log for one webhook: each attempt's event id and type, attempt number, status (delivered, failed or pending), HTTP status, error and next attempt time. Pass nextCursor back as after for the next page.

  • Requires stream:read.
  • limit is 1–200 (default 50). The node keeps deliveries for 7 days.
  • 503 STREAM_NODE_UNAVAILABLE when the stream node does not answer.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
webhookIdpathYesstring—
afterqueryNostring—
limitqueryNonumber—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "deliveries": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "webhook": {
                    "type": "string"
                  },
                  "event": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "attempt": {
                    "type": "number"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "failed",
                      "delivered"
                    ]
                  },
                  "httpStatus": {
                    "type": "number",
                    "nullable": true
                  },
                  "error": {
                    "type": "string",
                    "nullable": true
                  },
                  "at": {
                    "type": "string"
                  },
                  "nextAttemptAt": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "id",
                  "webhook",
                  "event",
                  "type",
                  "attempt",
                  "status",
                  "httpStatus",
                  "error",
                  "at",
                  "nextAttemptAt"
                ],
                "additionalProperties": false
              }
            },
            "nextCursor": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "deliveries",
            "nextCursor"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "deliveries": [
          {
            "id": "string",
            "webhook": "string",
            "event": "string",
            "type": "string",
            "attempt": 0,
            "status": "pending",
            "httpStatus": 0,
            "error": "string",
            "at": "string",
            "nextAttemptAt": "string"
          }
        ],
        "nextCursor": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTSend a test deliveryDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/webhooks/:webhookId/test

Send one signed webhook.test event to the webhook's URL now, from the Dashboard rather than the node, and report ok, statusCode, durationMs and error.

  • Requires stream:admin.
  • A delivery succeeds on any 2xx answer within 10 seconds; redirects are not followed.
  • A host that resolves to a private, loopback or reserved address is not called: the result has ok: false and an error, not an error status.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
webhookIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "ok": {
              "type": "boolean"
            },
            "statusCode": {
              "type": "number",
              "nullable": true
            },
            "durationMs": {
              "type": "number",
              "nullable": true
            },
            "error": {
              "type": "string",
              "nullable": true
            }
          },
          "required": [
            "ok",
            "statusCode",
            "durationMs",
            "error"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "ok": true,
        "statusCode": 0,
        "durationMs": 0,
        "error": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
PUTUpdate a webhookDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/webhooks/:webhookId/update

Change a webhook's url, events or enabled state. The signing secret stays the same.

  • Requires stream:admin.
  • Send revision equal to the webhook's current revision; if it changed meanwhile you get 409 STREAM_REVISION_CONFLICT.
  • An invalid URL returns 422 STREAM_INVALID (code invalid_url).
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
webhookIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
revisionnumberYes
urlstringNo
eventsstring[]No
enabledbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "revision": {
      "type": "number"
    },
    "url": {
      "type": "string"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "revision"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "webhook": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "events": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "enabled": {
                  "type": "boolean"
                },
                "fingerprint": {
                  "type": "string"
                },
                "revision": {
                  "type": "number"
                },
                "createdByUserId": {
                  "type": "string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "updatedAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "url",
                "events",
                "enabled",
                "fingerprint",
                "revision",
                "createdByUserId",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                },
                "warnings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "path": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      },
                      "message": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "path",
                      "code",
                      "message"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "status",
                "generation",
                "error",
                "warnings"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "webhook",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "webhook": {
          "id": "string",
          "url": "string",
          "events": [
            "string"
          ],
          "enabled": true,
          "fingerprint": "string",
          "revision": 0,
          "createdByUserId": "string",
          "createdAt": "string",
          "updatedAt": "string"
        },
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string",
          "warnings": [
            {
              "path": "string",
              "code": "string",
              "message": "string"
            }
          ]
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top