> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goodgrants.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive event notifications from Good Grants using webhooks configured by grant managers.

## Manage webhooks

<AccordionGroup>
  <Accordion title="Create a webhook">
    <Steps>
      <Step title="In Good Grants, go to Settings > Integrations > Webhooks" />

      <Step title="Click New webhook" />

      <Step title="Enter Name" />

      <Step title="Enter Webhook URL" />

      <Step title="Use the auto-generated Signing key or create a new one" />

      <Step title="Select Event subscriptions" />

      <Step title="Specify notification email addresses if needed. Separate each address with a comma (,) or semicolon (;)" />

      <Step title="Click Save" />
    </Steps>
  </Accordion>

  <Accordion title="Edit webhook">
    <Steps>
      <Step title="In Good Grants, go to Settings > Integrations > Webhooks" />

      <Step title="Click the name of the webhook to edit" />

      <Step title="Make your changes" />

      <Step title="Click Save" />
    </Steps>
  </Accordion>

  <Accordion title="Delete a webhook">
    <Steps>
      <Step title="In Good Grants, go to Settings > Integrations > Webhooks" />

      <Step title="Select the checkbox next to the webhook, then use the Action button to delete it" />

      <Step title="Click OK in the confirmation dialog" />
    </Steps>
  </Accordion>
</AccordionGroup>

## Webhook payloads

Webhook payloads are provided in JSON format and always contain the following attributes:

<ParamField header="event" type="string" required>
  Enumerated string with possible values being one of the events described in the following sections.
</ParamField>

<ParamField header="timestamp" type="string" required>
  ISO 8601 formatted datetime value, for example `2020-01-01T00:00:00Z`.
</ParamField>

<ParamField header="trigger" type="string" required>
  Machine-readable event key that fired the webhook. Enumerated string with possible values matching the event codes described in the following sections.
</ParamField>

<ParamField header="source" type="string" required>
  Enumerated string with the following possible values:

  * `ui` (default)
  * `api`
</ParamField>

### Signature

Use the `Signature` header to validate the webhook payload.

The signature value is generated with this algorithm, using the **Signing key** specified in the webhook and the JSON payload:

<CodeGroup>
  ```php PHP theme={null}
  $signature = hash_hmac('sha256', $payloadJsonString, $signingKey);
  ```

  ```js JavaScript theme={null}
  const crypto = require('crypto');
  const signature = crypto
    .createHmac('sha256', signingKey)
    .update(payloadJsonString)
    .digest('hex');
  ```

  ```python Python theme={null}
  import hmac
  import hashlib
  signature = hmac.new(
      signingKey.encode(),
      payloadJsonString.encode(),
      hashlib.sha256
  ).hexdigest()
  ```

  ```csharp C# theme={null}
  using System.Security.Cryptography;
  using System.Text;
  var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signingKey));
  var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payloadJsonString));
  var signature = BitConverter.ToString(hash).Replace("-", "").ToLower();
  ```

  ```java Java theme={null}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  Mac mac = Mac.getInstance("HmacSHA256");
  SecretKeySpec keySpec = new SecretKeySpec(
      signingKey.getBytes("UTF-8"), "HmacSHA256");
  mac.init(keySpec);
  byte[] hash = mac.doFinal(payloadJsonString.getBytes("UTF-8"));
  StringBuilder sb = new StringBuilder();
  for (byte b : hash) sb.append(String.format("%02x", b));
  String signature = sb.toString();
  ```
</CodeGroup>

Generate the same value in your endpoint and compare it with the `Signature` header value.

### Available event subscriptions

<AccordionGroup>
  <Accordion title="Allocation events">
    | Event                               | Description                                        |
    | ----------------------------------- | -------------------------------------------------- |
    | `allocation_created`                | Fired when a new allocation is created.            |
    | `allocation_payment_created`        | Fired when an allocation payment is created.       |
    | `allocation_payment_deleted`        | Fired when an allocation payment is deleted.       |
    | `allocation_payment_status_changed` | Fired when an allocation payment's status changes. |
    | `allocation_payment_updated`        | Fired when an allocation payment is updated.       |
  </Accordion>

  <Accordion title="Application events">
    | Event                           | Description                                                   |
    | ------------------------------- | ------------------------------------------------------------- |
    | `action_task_created`           | Fired when an action task is created for a reviewer.          |
    | `action_task_submitted`         | Fired when an action task is submitted by a reviewer.         |
    | `application_chapter_changed`   | Fired when an application's chapter is changed.               |
    | `application_copied`            | Fired when an application is copied.                          |
    | `application_created`           | Fired when a new application is created.                      |
    | `application_deleted`           | Fired when an application is deleted.                         |
    | `application_eligible`          | Fired when an application is marked as eligible.              |
    | `application_ineligible`        | Fired when an application is marked as ineligible.            |
    | `application_moderated`         | Fired when an application is moderated.                       |
    | `application_resubmitted`       | Fired when an application is resubmitted by the applicant.    |
    | `application_submitted`         | Fired when an application is submitted by the applicant.      |
    | `application_tagged`            | Fired when a tag is applied to an application.                |
    | `application_updated`           | Fired when an existing application is updated.                |
    | `applications_category_changed` | Fired when an application's category is changed.              |
    | `collaborator_invited`          | Fired when a collaborator is invited to an application.       |
    | `field_value_updated`           | Fired when a custom field value is updated on an application. |
  </Accordion>

  <Accordion title="Assignment events">
    | Event                  | Description                                            |
    | ---------------------- | ------------------------------------------------------ |
    | `assignment_completed` | Fired when an assignment is completed by a reviewer.   |
    | `assignment_created`   | Fired when a new assignment is created for a reviewer. |
  </Accordion>

  <Accordion title="Document events">
    | Event              | Description                                           |
    | ------------------ | ----------------------------------------------------- |
    | `document_created` | Fired when a new document is added to an application. |
    | `document_deleted` | Fired when a document is removed from an application. |
    | `document_updated` | Fired when an existing document is updated.           |
  </Accordion>

  <Accordion title="Grant report events">
    | Event                    | Description                             |
    | ------------------------ | --------------------------------------- |
    | `grant_report_created`   | Fired when a grant report is created.   |
    | `grant_report_submitted` | Fired when a grant report is submitted. |
  </Accordion>

  <Accordion title="Grant status events">
    | Event                  | Description                             |
    | ---------------------- | --------------------------------------- |
    | `grant_status_changed` | Fired when a grant's status is changed. |
  </Accordion>

  <Accordion title="Order payment events">
    | Event                   | Description                                            |
    | ----------------------- | ------------------------------------------------------ |
    | `order_payment_pending` | Fired when an order payment is marked as pending.      |
    | `order_payment_success` | Fired when an order payment is completed successfully. |
  </Accordion>

  <Accordion title="User events">
    | Event                   | Description                                       |
    | ----------------------- | ------------------------------------------------- |
    | `membership_registered` | Fired when a new user registers or is created.    |
    | `role_granted`          | Fired when a role is granted to a user.           |
    | `user_updated`          | Fired when an existing user's profile is updated. |
  </Accordion>
</AccordionGroup>