Webhook Documentation Suggestions

[Kaelten]

While understanding hooks I ran across a few thoughts.

1. The documentation provided for the schema doesn't include the variations of possible values/types depending on when the hook is triggered.
2. The fastapi example could benefit from providing the pydantic models needed to parse the api.
3. It strikes me as odd that only URI is uppercase, guessing this is an encoding artifact based on how rust's serialization works
4. I was a little surprised that the hook name wasn't available in the payload, but not a huge deal either way.

To help address the first two thoughts, here is the schema I've reversed engineered from watching the hooks over several types of uploads. I'm not sure I've captured all the variations yet.

import datetime
import uuid

from pydantic import BaseModel, conint, Field

class UploadInfo(BaseModel):
    id: uuid.UUID
    offset: conint(ge=0)
    length: conint(ge=0) | None
    path: str | None
    created_at: datetime.datetime
    deferred_size: bool
    is_partial: bool
    is_final: bool
    parts: list[uuid.UUID] | None
    storage: str
    metadata: dict


class RequestInfo(BaseModel):
    uri: str = Field(alias='URI')
    method: str
    remote_addr: str
    headers: dict


class RustusPayload(BaseModel):
    upload: UploadInfo
    request: RequestInfo

I'd also suggest providing example payloads for each event type that covers the variations or at least document when a field can be in different states. i.e. parts is None unless it's a concat finalization in which it gives the ids of the other parts.

[s3rius]

Maybe it would be better if we change the format of hooks to be more intuitive.

And I guess changing URI to uri is a good thing.

[Kaelten]

I think there's an argument for cleaning up and introducing a new format (for backwards compatibility at least) that'd be a little clearer. Happy to collaborate on the schema if you'd like.

[s3rius]

I guess we can break backwards compatibility, if we bump major version of the project. I don't think there will be a lot of difference to current format. But if the difference is huge I don't mind introducing new format.

[s3rius]

I updated docs and added new format (v2) where URI is lowercase. Will release in 0.5.8. Please check it out.

[Kaelten]

will look soon!

[Kaelten]

New documentation updates is a big upgrade. I'll test upgraded to .8 and switching over to the v2 format soon.

[s3rius]

New documentation updates is a big upgrade. I'll test upgraded to .8 and switching over to the v2 format soon.

Cool. I'm waiting for it.

[s3rius]

Closed due to inactivity.