[WEBHOOK]: Initial integration

[amadolid]

WEBHOOK

• webhook walker is similar to normal authenticated walker however, normal authenticated walker is associated to a user while webhook is directly to root.
• webhook api keys are manage by user
• supports different HTTP components as API key holder
  • header (default):
  • query
  • path
  • body
• name of the api-key can be change to any string (default: X-API-KEY)

CREATE WEBHOOK

walker webhook {
    can enter1 with `root entry {
        report here;
    }

    class __specs__ {
        has webhook: dict = {
            "type": "header | query | path | body", # optional: defaults to header
            "name": "any string" # optional: defaults to X-API-KEY
        };
    }
}

WEBHOOK MANAGEMENT APIs

GENERATE API KEY

REQUEST

POST /webhook/generate-key

{
  # unique name of webhook
  "name": "webhook1",
  
  # names of allowed webhook walkers. Not set or empty list means all webhook walkers is allowed.
  "walkers": ["webhook"], 
  
  # names of allowed nodes. Not set or empty list means all nodes is allowed.
  "nodes": ["root"],
  
  # date now + timedelta( {{interval}}: {{count}} )
  "expiration": {
    "count": 60,
    
    # seconds | minutes | hours | days
    "interval": "days"
  }
}

RESPONSE

{
  "id": "672203ee093fd3d208a4b6d4",
  "name": "webhook1",
  "key": "6721f000ee301e1d54c3de3d:1730282478:P4Nrs3DOLIkaw5aYsbIWNzWZZAwEyb20"
}

GET API KEY

REQUEST

GET /webhook

RESPONSE

{
  "keys": [
    {
      "id": "672203ee093fd3d208a4b6d4",
      "name": "test",
      "root_id": "6721f000ee301e1d54c3de3d",
      "walkers": ["webhook"],
      "nodes": ["root"],
      "expiration": "2025-12-24T10:01:18.206000",
      "key": "6721f000ee301e1d54c3de3d:1730282478:P4Nrs3DOLIkaw5aYsbIWNzWZZAwEyb20"
    }
  ]
}

EXTEND API KEY

REQUEST

PATCH /webhook/extend/{id}

{
  "count": 60,
    
  # seconds | minutes | hours | days
  "interval": "days"
}

RESPONSE

{
  "message": "Successfully Extended!"
}

DELETE API KEY

REQUEST

DELETE /webhook/delete

{
  # list of id to be deleted
  "ids": ["672203ee093fd3d208a4b6d4"]
}

RESPONSE

{
  "message": "Successfully Deleted!"
}

[amadolid]

backup
https://github.com/amadolid/jaseci/tree/webhook-backup

[amadolid]

REBASED

[ypkang]

Update the specs options to include using header/path/body for the webhook authentication key.

[ypkang]

@amadolid Tested this and I have one question

What should the URL look like for the path option for the key? I tried /webhook/walker/webhook/API_KEY_HERE and doesn't seem to work.

Otherwise, this works as expected, resolve the conflict and the comments and I can merge this.

[amadolid]

@amadolid Tested this and I have one question

What should the URL look like for the path option for the key? I tried /webhook/walker/webhook/API_KEY_HERE and doesn't seem to work.

Otherwise, this works as expected, resolve the conflict and the comments and I can merge this.

Here's the sample webhook using path as auth

walker webhook {
    can enter1 with `root entry {
        report here;
    }

    class __specs__ {
        has webhook: dict = {"type": "path", "name": "key"}, path: str = "/{key}";
    }
}

Here's how to call it

curl -X 'POST' \
  'http://localhost:8001/webhook/walker/webhook/676cf326532283bae2b574b5%3A1736237645%3AmnSMcWwdmdYD90rLyXUCBEDGFVHJEceR' \
  -H 'accept: application/json' \
  -d ''

[ypkang]

@amadolid Tested this and I have one question
What should the URL look like for the path option for the key? I tried /webhook/walker/webhook/API_KEY_HERE and doesn't seem to work.
Otherwise, this works as expected, resolve the conflict and the comments and I can merge this.

Here's the sample webhook using path as auth

walker webhook {
    can enter1 with `root entry {
        report here;
    }

    class __specs__ {
        has webhook: dict = {"type": "path", "name": "key"}, path: str = "/{key}";
    }
}

Here's how to call it

curl -X 'POST' \
  'http://localhost:8001/webhook/walker/webhook/676cf326532283bae2b574b5%3A1736237645%3AmnSMcWwdmdYD90rLyXUCBEDGFVHJEceR' \
  -H 'accept: application/json' \
  -d ''

I see. We need to document this. Can you add one example each for each type (header/path/query/payload) just like what you did here and include it in the documentation?

[ypkang]

Good to merge this one. I'd like someone to use this to validate it covers the common use case.

@ChrisIsKing i think you were trying to use webhook for a messaging platform integration right? Could you take this for a spin?