Event sources
Supported event source types and their event types
Event source instructions
You can provide custom instructions for each event source. These instructions are shown to the user when installing the snap-in. The instructions are written in markdown and can be provided in the setup_instructions field of the event source.
To provide dynamic instructions, you can access some metadata from event source objects. The following fields are accessible:
{{source.name}}: Name of the event source{{source.trigger_url}}: Webhook URL{{source.config.<field_name>}}: Fields from within the event source configuration
For example:
DevRev Webhook
The devrev-webhook event source can be used to listen for events occuring on DevRev. These includes events like work_created and conversation_updated.
The payload of the events is defined by the Webhooks Event Schema.
Webhook-event-request example:
Webhook Filters
To limit the events being sent to a webhook, you can also specify a jq query as a filter. This filter is applied on the webhook before the event is dispatched. If no filter is specified, then all events are sent.
The jq query can reference the event payload as . and the user creating the webhook as $user. The $user object only contains one string field: the id of the webhook creator.
The filter must return a boolean value. If the filter returns true, the event is dispatched to the webhook. If the filter returns false, the event is not dispatched to the webhook.
For example, to create an event source which listens for issue creation and comments on issues, you can define the event source as follows:
Scheduled events
flow-events are an event source that snap-ins can use to publish or schedule events directly. This event source can then be used to trigger another automation. This capability makes it ideal for building snap-ins that need to act later. For example, sending reminders to issues still in the Triage stage.
You create an event source of type flow-events, and from your snap-in, you call the DevRev API to schedule an event for this event source. The following example illustrates how this works:
manifest.yaml
In this example, the first automation schedules an event with a delay of 30 seconds for the event source scheduled-events.
The second automation then binds function_2 to this event source. So the scheduled event executes function_2 30 seconds after the work is created.
In function_1, you can publish the event as follows:
In function_2, you can use the payload of the scheduled event as follows:
The /event-sources.schedule API is currently in early access. For API details, see event-sources-schedule-event.
To cancel scheduled events, you can utilize the /event-sources.unschedule API. For API details, see event-sources-delete-scheduled-event.
Generic event sources
You can create a generic event source if you need an event source not supported by DevRev. A generic event source includes a webhook URL and developer-provided code on how to validate the events coming on the URL.
For example, let’s say you want to connect to a source that can publish events to a webhook URL, and it hashes the entire request payload with the shared secret and adds an HTTP header X-Signature-256 with value as the hash. Then, you can provide the custom code (currently in rego) to validate the payload with the same algorithm. You would also calculate the hash and verify with the value present in the header to avoid someone else tampering in between.
To create a generic event source in your manifest, you create an event source with the type flow-custom-webhook and config containing a key policy which contains the rego code.
The input passed to the policy is the following JSON:
The policy must return an object output in the following format:
Example of a generic event source. This event source authenticates the incoming request by checking the header X-Signature-256.
The event_key output of the policy can be used to define an automation on the event custom:event_key. For example:
Here, you are creating an event source with the name custom-webhook, and the policy validates that there should be a header X-Signature-256 with a value of HMAC-SHA256 of raw request body.
A sample curl command to trigger this event source manually is:
Timer-based event sources
Timer-based event sources can be created to send events based on intervals and cron schedules. In the following example, you have two event sources, one emits events daily at 12:00am, the other every hour (3600 seconds). In the event payload, you see the JSON field metadata you specified in the event source configuration.
The automation event type for timer events is timer.tick. To initiate an automation based on timer events, use the following syntax in manifest.yaml:
The payload contains the metadata fields you specified in the event source configuration. For example, {"event_key": "daily_events"} for the daily-timer-source.
Email-based event sources
You can create an email-based event source that can be used to write automations on top of emails. For this, a sample of the YAML is shown below:
The event type of the events emitted by this event source is email.receive.
When a snap-in using such an event source is deployed, the instructions show a unique email address. You have to set up forwarding in your original
email inbox or Google Group to this email address. In the example above, if the forwarding address is v1.abc.xyz@hooks.devrev.ai, you should set up email
forwarding from test@company.com to v1.abc.xyz@hooks.devrev.ai.
Only emails forwarded from the allowlist of emails/domains are emitted as events. Hence, this event source should be used for email forwarding only, not as a direct mailbox to which anyone can send their emails. Emails received (either directly or by forwarding) from senders who aren’t in the allowlist are dropped. There are a few exceptions to this like Google’s forwarding confirmation emails.
The allowlist can either contain an email address or an entire domain. Strict matching is done for domains, meaning that subdomains are not included.
The email protocol regarding forwarding is not very well defined. We’ve tested forwarding from common sources like Gmail, Google Groups, and Outlook Inbox. However, if you’re having issues with email forwarding on other providers, feel free to contact us.
Payload
Below is a sample payload of the events produced by the email event source:
Below is a brief description of the fields:
emailBody: The plain text body of the email.htmlBody: The HTML body of the email.from: List of from email addresses of the email.to,cc,bcc: List of recipient email addresses.inReplyToId: Message ID of the email (if received mail is a reply to some other previous mail).messageId: Message ID of the received email.rawBodyartifactId: artifact ID for the raw email (in MIME format) received on the event source. You can use the artifact APIs to download this email if you need to.artifactIds: artifact IDs for attachments in the email.replyTo: Reply-To header of the email.sentOn: Timestamp when email was sent (in UTC).subject: Subject of the email.