Request Handler (WebHook, Callback)

Add a Request Handler

The following steps add a new RequestHandler in dbFront:

1. Open the Preferences on the Database which will host the RequestHandler,
2. Open the Request Handlers tab,
3. Click Add New to open the New Request Handler dialogue,
4. Set the "Handle" to a string that clearly and tersely describes the service (No Spaces),
5. Set the "Procedure Name" to an existing stored procedure (more details below),
6. Set "Run As" to "Current User" for user-initiated requests, or "Anonymous" for requests that are externally initiated,
7. Save the new Request Handler, and then also save the Database preferences to complete the save. (Two Saves)

Once saved, you can re-open the Request Handler to view the Activation URL.

Request Handler Procedure

The Request Handler stored procedures are expected to have two parameters.

• Header: The first parameter receives a JSON structure that details the current request state.  The field type should be at least VARCHAR(2000).
• Data: The second field receives the raw data and should be typed accordingly.  For form data, the recommendation is at least VARCHAR(2000).

The "Result Type":

• (Discard Results): This will cause the procedure results to be discarded.
• Automatic: dbFront checks the returned data and selects the correct type automatically.  Can also trigger the ProcedureAPI.
• Server Directed (ProcedureAPI): A custom action as specified by the stored procedure,
• Simple Html: Return the value from the first column and row as HTML that will be shown in a dialogue.
• Simple Message: Return the value from the first column and row as a simple message.
• Simple Table: Build and display one or more HTML Table(s) using the result set.

Server Directed (ProcedureAPI)

The Server Directed (ProcedureAPI) output format allows stored procedures to dynamically send commands to dbFront.  The command is returned as a multicolumn select with the first column named "action".  Not only can a stored procedure make specific requests, but the data is optionally returned to the procedure for further processing.  This allows stored procedures to have a two-way conversation with dbFront (and the user) via the ProcedureAPI:

• Continually refresh a stored procedure result until the processing is finished,
• Display an HTML-formatted message with custom buttons, (the button click is sent to the procedure for processing)
• Procedure-generated forms with the form data and button clicks processed by the procedure,
• Send/Process WebRequests,
• Send Email.

For more details and examples, see: ProcedureAPI

Security

The "Run As" property of the Request Handler is set to either "Current User" or "Anonymous".  Changing this setting will change the activation URL.

Current User

If the request was initiated by the user and if the response is expected to be in the user context, then the security should be set to "Current User".  Some use cases are:

• OAuth Completion (Github OAuth Example),
• Payment Confirmations.

Anonymous

For externally initiated requests, the security should be set to Anonymous.  Some use cases are:

• Anonymous User Registration or Forgot Password Forms,
• Webhooks to notify your application about: payments, updates or other transactions or events.

Trouble Shooting

• Can't load '%procedurename%' parameters. The stored procedure '%procedurename%' doesn't exist.
  The three most likely sources for this error are:
  1. Incorrect procedure name,
  2. Missing schema name for procedures saved in non-default schemas,
  3. Missing security.  Run [Grant Execute]