Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/userguide/webhooks.diviner
@title User Guide: Webhooks | @title User Guide: Webhooks | ||||
@group userguide | @group userguide | ||||
Guide to configuring webhooks. | Guide to configuring webhooks. | ||||
Overview | Overview | ||||
======== | ======== | ||||
If you'd like to react to events in Phabricator or publish them into external | If you'd like to react to events in Phorge or publish them into external | ||||
systems, you can configure webhooks. | systems, you can configure webhooks. | ||||
Configure webhooks in {nav Herald > Webhooks}. Users must have the | Configure webhooks in {nav Herald > Webhooks}. Users must have the | ||||
"Can Create Webhooks" permission to create new webhooks. | "Can Create Webhooks" permission to create new webhooks. | ||||
Triggering Hooks | Triggering Hooks | ||||
================ | ================ | ||||
Show All 11 Lines | |||||
============= | ============= | ||||
To test a webhook, use {nav New Test Request} from the web interface. | To test a webhook, use {nav New Test Request} from the web interface. | ||||
You can also use the command-line tool, which supports a few additional | You can also use the command-line tool, which supports a few additional | ||||
options: | options: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/webhook call --id 42 --object D123 | phorge/ $ ./bin/webhook call --id 42 --object D123 | ||||
``` | ``` | ||||
Verifying Requests | Verifying Requests | ||||
================== | ================== | ||||
When your webhook callback URI receives a request, it didn't necessarily come | When your webhook callback URI receives a request, it didn't necessarily come | ||||
from Phabricator. An attacker or mischievous user can normally call your hook | from Phorge. An attacker or mischievous user can normally call your hook | ||||
directly and pretend to be notifying you of an event. | directly and pretend to be notifying you of an event. | ||||
To verify that the request is authentic, first retrieve the webhook key from | To verify that the request is authentic, first retrieve the webhook key from | ||||
the web UI with {nav View HMAC Key}. This is a shared secret which will let you | the web UI with {nav View HMAC Key}. This is a shared secret which will let you | ||||
verify that Phabricator originated a request. | verify that Phorge originated a request. | ||||
When you receive a request, compute the SHA256 HMAC value of the request body | When you receive a request, compute the SHA256 HMAC value of the request body | ||||
using the HMAC key as the key. The value should match the value in the | using the HMAC key as the key. The value should match the value in the | ||||
`X-Phabricator-Webhook-Signature` field. | `X-Phabricator-Webhook-Signature` field. | ||||
To compute the SHA256 HMAC of a string in PHP, do this: | To compute the SHA256 HMAC of a string in PHP, do this: | ||||
```lang=php | ```lang=php | ||||
▲ Show 20 Lines • Show All 59 Lines • ▼ Show 20 Lines | |||||
is triggered by Herald rules, the specific rules which triggered the call will | is triggered by Herald rules, the specific rules which triggered the call will | ||||
be listed. For firehose rules, the rule itself will be listed as the trigger. | be listed. For firehose rules, the rule itself will be listed as the trigger. | ||||
For test calls, the user making the request will be listed as a trigger. | For test calls, the user making the request will be listed as a trigger. | ||||
The **action** map has metadata about the action: | The **action** map has metadata about the action: | ||||
- `test` This was a test call from the web UI or console. | - `test` This was a test call from the web UI or console. | ||||
- `silent` This is a silent edit which won't send mail or notifications in | - `silent` This is a silent edit which won't send mail or notifications in | ||||
Phabricator. If your hook is doing something like copying events into | Phorge. If your hook is doing something like copying events into | ||||
a chatroom, it may want to respect this flag. | a chatroom, it may want to respect this flag. | ||||
- `secure` Details about this object should only be transmitted over | - `secure` Details about this object should only be transmitted over | ||||
secure channels. Your hook may want to respect this flag. | secure channels. Your hook may want to respect this flag. | ||||
- `epoch` The epoch timestamp when the callback was queued. | - `epoch` The epoch timestamp when the callback was queued. | ||||
The **transactions** list contains information about the actual changes which | The **transactions** list contains information about the actual changes which | ||||
triggered the callback. | triggered the callback. | ||||
▲ Show 20 Lines • Show All 57 Lines • ▼ Show 20 Lines | |||||
are made. The web UI shows a warning indicator when a hook is paused because of | are made. The web UI shows a warning indicator when a hook is paused because of | ||||
errors. | errors. | ||||
Hook requests time out after 10 seconds. Consider offloading response handling | Hook requests time out after 10 seconds. Consider offloading response handling | ||||
to some kind of worker queue if you expect to routinely require more than 10 | to some kind of worker queue if you expect to routinely require more than 10 | ||||
seconds to respond to requests. | seconds to respond to requests. | ||||
Hook callbacks are single-threaded: you will never receive more than one | Hook callbacks are single-threaded: you will never receive more than one | ||||
simultaneous call to the same webhook from Phabricator. If you have a firehose | simultaneous call to the same webhook from Phorge. If you have a firehose | ||||
hook on an active install, it may be important to respond to requests quickly | hook on an active install, it may be important to respond to requests quickly | ||||
to avoid accumulating a backlog. | to avoid accumulating a backlog. | ||||
Callbacks may be invoked out-of-order. You should not assume that the order | Callbacks may be invoked out-of-order. You should not assume that the order | ||||
you receive requests in is chronological order. If your hook is order-dependent, | you receive requests in is chronological order. If your hook is order-dependent, | ||||
you can ignore the transactions in the callback and use `transaction.search` to | you can ignore the transactions in the callback and use `transaction.search` to | ||||
retrieve a consistent list of ordered changes to the object. | retrieve a consistent list of ordered changes to the object. | ||||
Show All 14 Lines |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0