Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cocobase.cc/llms.txt

Use this file to discover all available pages before exploring further.

​
Hooks

Hooks let you attach cloud functions to lifecycle events in your project — document changes, user registration, login, and more. When the event fires, Cocobase calls your function automatically with the relevant data.
Hooks are configured in the Cocobase Dashboard. Your cloud functions must already be deployed before you can attach them to a hook.

​
How Hooks Work

Every hook calls your cloud function via HTTP with a JSON payload containing the event data. Inside your function you access it through req.payload: 
def main():
    event = req.payload.get("event")       # e.g. "pre_save", "post_login"
    document = req.payload.get("document") # the document data (collection hooks)
    user = req.payload.get("user")         # the user data (auth hooks)
    return {"ok": True}
Hooks also send an X-Hook-Event header with the event name string, useful if one function handles multiple events.

​
Two Types of Hooks

​
Collection Hooks

Attached to a specific collection. Fire when documents in that collection are created, updated, or deleted.
EventWhen
pre_saveBefore a document is created or updated
post_saveAfter a document is created or updated
pre_deleteBefore a document is deleted
post_deleteAfter a document is deleted

​
Auth Hooks

Attached to your project’s app-user system (not a specific collection). Fire during the authentication lifecycle.
EventWhenCan Block?
pre_registerBefore a new user is saved to the database✅ Yes
post_registerAfter a new user is successfully registeredNo
pre_loginAfter password verified, before token is issued✅ Yes
post_loginAfter a user logs in and receives a tokenNo
pre_user_updateBefore a user’s profile is updatedNo
post_user_updateAfter a user’s profile is updatedNo
pre_user_deleteBefore a user is deletedNo
post_user_deleteAfter a user is deletedNo

​
Blocking vs Background Hooks

​
Background (fire-and-forget)

Most hooks run in the background — Cocobase fires the function and does not wait for a response. The main operation (save, delete, login) completes immediately. Errors in your function are logged but never affect the user.

​
Blocking (pre_login, pre_register)

pre_login and pre_register run synchronously and can cancel the operation. If your function returns {"block": true, "reason": "..."}, Cocobase rejects the request with a 403 and sends reason back to the caller. 
# Block the operation
return {"block": True, "reason": "Account suspended."}

# Allow the operation
return {"block": False}
# or just return nothing — silence means allow
Fail-open: If your function times out, crashes, or is unreachable, Cocobase allows the operation to proceed. A broken hook will never lock users out.

​
Setting Up Hooks

​
Collection Hooks

  1. Go to Dashboard → Your Project → Collections
  2. Click the collection you want to attach a hook to
  3. Open the Settings tab
  4. Click Add Hook
  5. Choose an event and select your cloud function
  6. Save

​
Auth Hooks

  1. Go to Dashboard → Your Project → App Users
  2. Click the Auth Hooks tab
  3. Click Add Hook
  4. Choose an event and select your cloud function
  5. Save

​
Next Steps

  • Collection Hooks — Full reference for pre_save, post_save, pre_delete, post_delete
  • Auth Hooks — Full reference for all auth lifecycle events
  • Hook Examples — Copy-paste recipes for common use cases